updates

Author: calad0i

docs/advanced/extension.rst

@@ -26,14 +26,14 @@ For concreteness, let's say our custom layer ``KReverse`` is implemented in Kera
 .. code-block:: Python
 
     # Keras implementation of a custom layer
-    class KReverse(tf.keras.layers.Layer):
+    class KReverse(keras.layers.Layer):
         '''Keras implementation of a hypothetical custom layer'''
 
         def __init__(self):
             super().__init__()
 
         def call(self, inputs):
-            return tf.reverse(inputs, axis=[-1])
+            return inputs[..., ::-1]
 
         def get_config(self):
             return super().get_config()
@@ -58,19 +58,42 @@ This parser reads the attributes of the Keras layer instance and populates a dic
 It also returns a list of output shapes (one sjape for each output).
 In this case, there a single output with the same shape as the input.
 
-.. code-block:: Python
+.. tabs::
+    .. tab:: Keras v2
+    .. code-block:: Python
+
+        # Parser for converter
+        def parse_reverse_layer(keras_layer, input_names, input_shapes, data_reader):
+            layer = {}
+            layer['class_name'] = 'KReverse'
+            layer['name'] = keras_layer['config']['name']
+            layer['n_in'] = input_shapes[0][1]
+
+            if input_names is not None:
+                layer['inputs'] = input_names
+
+            return layer, [shape for shape in input_shapes[0]]
+
+    .. tab:: Keras v3
+    .. code-block:: Python
 
-    # Parser for converter
-    def parse_reverse_layer(keras_layer, input_names, input_shapes, data_reader):
-        layer = {}
-        layer['class_name'] = 'HReverse'
-        layer['name'] = keras_layer['config']['name']
-        layer['n_in'] = input_shapes[0][1]
+        from hls4ml.converters.keras_v3._base import register, KerasV3LayerHandler
 
-        if input_names is not None:
-            layer['inputs'] = input_names
+        @register
+        class KReverseHandler(KerasV3LayerHandler):
+            '''Keras v3 layer handler for KReverse'''
 
-        return layer, [shape for shape in input_shapes[0]]
+            handles = ('KReverse',)
+            def handle(
+                self,
+                layer: 'keras.Layer',
+                in_tensors: Sequence['KerasTensor'],
+                out_tensors: Sequence['KerasTensor'],
+            ) -> dict[str, Any] | tuple[dict[str, Any], ...]:
+                # Only layer-specific parameters are needed.
+                # Common parameters are automatically added in the base class.
+                assert len(in_tensors[0].shape) == 2, 'KReverse is only supported for 2D tensors'
+                return {'n_in': in_tensors[0].shape[-1]}
 
 Next, we need the actual HLS implementaton of the function, which can be written in a header file ``nnet_reverse.h``.
 
@@ -144,30 +167,29 @@ In this case, the HLS code is valid for both the Vivado and Quartus backends.
     # For keras v3, use register on subclassed KerasV3LayerHandler from hls4ml.converters.keras_v3._base instead
 
     # Register the hls4ml's IR layer
-    hls4ml.model.layers.register_layer('HReverse', HReverse)
+    hls4ml.model.layers.register_layer('KReverse', HReverse)
 
     for backend_id in ['Vivado', 'Quartus']:
         # Register the optimization passes (if any)
         backend = hls4ml.backends.get_backend(backend_id)
-        backend.register_pass('remove_duplicate_reverse', RemoveDuplicateReverse, flow=f'{backend_id.lower()}:optimize')
 
         # Register template passes for the given backend
         backend.register_template(HReverseConfigTemplate)
         backend.register_template(HReverseFunctionTemplate)
 
         # Register HLS implementation
-        backend.register_source('nnet_reverse.h')
+        backend.register_source('/path/to/your/nnet_reverse.h')
 
 Finally, we can actually test the ``hls4ml`` custom layer compared to the Keras one.
 
 .. code-block:: Python
 
     # Test if it works
-    kmodel = tf.keras.models.Sequential(
+    kmodel = keras.models.Sequential(
         [
-            tf.keras.layers.Input(shape=(8,)),
+            keras.layers.Input(shape=(8,)),
             KReverse(),
-            tf.keras.layers.ReLU(),
+            keras.layers.ReLU(),
         ]
     )
 

docs/advanced/hgq.rst

@@ -3,7 +3,8 @@ High Granularity Quantization (HGQ2)
 ======================================
 
 .. note::
-   HGQ2 is the successor of the original `HGQ <./hgq1.html>`__. framework, which was built on Keras v2. HGQ2 built on top of Keras v3, leveraging its new features and improvements.
+   New projects are encouraged to use `HGQ2 <../hgq2.html>`_ instead of the original `HGQ <../hgq.html>`_.
+   HGQ2 extends the original HGQ with more supported layers, more quantizer options, and is on top of Keras v3, which can be used natively with JAX, PyTorch, and TensorFlow backends.
 
 .. image:: https://img.shields.io/badge/License-LGPLv3-blue.svg
    :target: https://www.gnu.org/licenses/lgpl-3.0.en.html

docs/advanced/hgq1.rst

@@ -2,6 +2,9 @@
 High Granularity Quantization (HGQ)
 ===================================
 
+.. note::
+   While still supported and maintained, HGQ is deprecated in favor of `HGQ2 <../hgq2.html>`_. New projects are strongly encouraged to use HGQ2 instead.
+
 .. image:: https://github.com/calad0i/HGQ/actions/workflows/sphinx-build.yml/badge.svg
    :target: https://calad0i.github.io/HGQ/
 .. image:: https://badge.fury.io/py/hgq.svg

docs/api/configuration.rst

@@ -73,7 +73,10 @@ for automatic setting of precisions.  The layer-level precisions with the ``'nam
 (see :ref:`Automatic precision inference`). Note that layer-level settings take precedence over model-level settings. A ``'name'`` granularity is required for QKeras
 and QONNX model parsing. Passing the backend to these functions is recommended because some configuration options depend on the backend. See :py:class:`~hls4ml.utils.config.config_from_keras_model`
 and similar for more information on the various options. Note specifically the documentation of :py:class:`~hls4ml.utils.config.config_from_pytorch_model` on how to handle differences in input data
-formats between pytorch and keras (hls4ml follows keras conventions internally). Note that passing precision configurations for HGQ/HGQ2 models is not needed in general, and **should not be done** without understanding the implications.
+formats between pytorch and keras (hls4ml follows keras conventions internally).
+
+.. warning::
+    Note that passing precision configurations when invoking the full model precision propagation (by default for HGQ/HGQ2 models, or when `bit_exact=True` is set for other frontends) is **not needed** and **should not be done** without understanding the implications.
 
 One can override specific values before using the configuration:
 

docs/conf.py

@@ -70,6 +70,7 @@ def get_pypi_version(package, url_pattern=URL_PATTERN):
     'sphinx.ext.napoleon',
     'sphinx_contributors',
     'sphinx_github_changelog',
+    'sphinx_tabs.tabs',
 ]
 
 # Note: to build locally, you will need to set the SPHINX_GITHUB_CHANGELOG_TOKEN
@@ -103,7 +104,7 @@ def get_pypi_version(package, url_pattern=URL_PATTERN):
 
 html_theme_options = {
     'canonical_url': '',
-    'analytics_id': '',  #  Provided by Google in your dashboard
+    'analytics_id': '',  # Provided by Google in your dashboard
     'logo_only': True,
     'display_version': True,
     'prev_next_buttons_location': 'bottom',

docs/frontend/keras.rst

@@ -18,6 +18,6 @@ The ``data_format='channels_first'`` parameter of Keras layers is supported for
 * `QKeras <https://github.com/fastmachinelearning/qkeras>`_
     The equivalent QKeras API and its quantizers are also supported by ``hls4ml``. QKeras is not compatible with Keras v3.
 * `HGQ <https://github.com/calad0i/HGQ>`_
-    The equivalent HGQ API is also supported.
+    The equivalent HGQ API is also supported. Still maintained but deprecated in favor of `HGQ2 <../hgq2.html>`_.
 * `HGQ2 <https://github.com/calad0i/HGQ2>`_
     The equivalent HGQ2 API is also supported, plus some additional advanced operators.

docs/intro/setup.rst

@@ -57,19 +57,19 @@ The following Python packages are all optional and are only required if you inte
    * `Brevitas <https://xilinx.github.io/brevitas/>`_: Based on PyTorch. See `frontend/pytorch <../frontend/pytorch.html>`_ for more details.
    * `QONNX <https://github.com/fastmachinelearning/qonnx>`_: Based on ONNX. See `frontend/onnx <../frontend/onnx.html>`_ for more details.
 
-Running C simulation from Python requires a C++11-compatible compiler. On Linux, a GCC C++ compiler ``g++`` is required. Any version from a recent Linux should work. On MacOS, the *clang*-based ``g++`` is enough. For the oneAPI backend, one must have oneAPI installed, along with the FPGA compiler, to run C/SYCL simulations.
+Running C simulation from Python requires a C++11-compatible compiler. On Linux, a GCC C++ compiler ``g++`` is required. Any version from a recent Linux should work. On MacOS, the *clang*-based ``g++`` is enough. For the oneAPI backend, one must have `oneAPI=2025.0` (2025.1 is known **not to work**) installed, along with the FPGA compiler, to run C/SYCL simulations.
 
 Specific functionalities may need additional Python packages. If any needed is missing, ``hls4ml`` will raise an error and prompt you to install the missing packages.
 
 To run FPGA synthesis, installation of following tools is required:
 
-* Xilinx Vivado HLS 2018.2 to 2020.1 for synthesis for Xilinx FPGAs using the ``Vivado`` backend.
+* Xilinx Vivado HLS 2020.1 for synthesis for Xilinx FPGAs using the ``Vivado`` backend. Older versions may work, but use at your own risk.
 
 * Vitis HLS 2022.2 or newer is required for synthesis for Xilinx FPGAs using the ``Vitis`` backend.
 
 * Intel Quartus 20.1 to 21.4 for the synthesis for Intel/Altera FPGAs using the ``Quartus`` backend.
 
-* oneAPI 2024.1 to 2025.0 with the FPGA compiler and recent Intel/Altera Quartus for Intel/Altera FPGAs using the ``oneAPI`` backend.
+* oneAPI 2024.1 to 2025.0 with the FPGA compiler and recent Intel/Altera Quartus for Intel/Altera FPGAs using the ``oneAPI`` backend. Newer versions are known **not to work**.
 
 Catapult HLS 2024.1_1 or 2024.2 can be used to synthesize both for ASICs and FPGAs.
 

docs/intro/status.rst

@@ -51,7 +51,9 @@ A summary of the on-going status of the ``hls4ml`` tool is in the table below.
 +-----------------------+-----+-----+--------------+--------+--------+-----+
 | Frontend/Backend      | MLP | CNN | RNN/LSTM/GRU | GarNet | Einsum | MHA |
 +=======================+=====+=====+==============+========+========+=====+
-| Keras v2/QKeras       | ✅  | ✅  | ✅           | ✅     | N/A    | ❌  |
+| Keras v2              | ✅  | ✅  | ✅           | ✅     | ❌     | ❌  |
++-----------------------+-----+-----+--------------+--------+--------+-----+
+| QKeras                | ✅  | ✅  | ✅           | ✅     | N/A    | N/A |
 +-----------------------+-----+-----+--------------+--------+--------+-----+
 | HGQ                   | ✅  | ✅  | N/A          | N/A    | N/A    | N/A |
 +-----------------------+-----+-----+--------------+--------+--------+-----+
@@ -63,7 +65,7 @@ A summary of the on-going status of the ``hls4ml`` tool is in the table below.
 +-----------------------+-----+-----+--------------+--------+--------+-----+
 | ONNX                  | ✅  | ✅  | ❌           | ❌     | ❌     | ❌  |
 +-----------------------+-----+-----+--------------+--------+--------+-----+
-| QONNX                 | ✅  | ✅  | N/A          | N/A    | N/A    | N/A |
+| QONNX                 | ✅  | ✅  | ❌           | N/A    | N/A    | N/A |
 +-----------------------+-----+-----+--------------+--------+--------+-----+
 | Vivado/Vitis HLS      | ✅  | ✅  | ✅           | ❌     | ✅     | ✅  |
 +-----------------------+-----+-----+--------------+--------+--------+-----+
@@ -82,7 +84,7 @@ Other feature notes:
   - Intel HLS versions 20.1 to 21.4, versions > 21.4 have not been tested.
   - Vitis HLS versions 2022.2 to 2024.1. Versions <= 2022.1 are known not to work.
   - Catapult HLS versions 2024.1_1 to 2024.2
-  - oneAPI versions 2024.1 to 2025.0. 2025.1 is known to not work.
+  - oneAPI versions 2024.1 to 2025.0. Any future versions are known to not work.
 
 * ``hls4ml`` supports Linux [*]_ and requires python >=3.10. hls4ml does not require a specific Linux distribution version and we recommend following the requirements of the HLS tool you are using.
 * Windows and macOS are not supported. Setting up ``hls4ml`` on these platforms, for example using the Windows Subsystem for Linux (WSL), should be possible, but we do not provide support for such use cases.

pyproject.toml

@@ -33,6 +33,7 @@ optional-dependencies.doc = [
   "sphinx-contributors",
   "sphinx-github-changelog",
   "sphinx-rtd-theme",
+  "sphinx-tabs",
 ]
 optional-dependencies.hgq = [ "hgq>=0.2.3" ]
 optional-dependencies.hgq2 = [ "hgq2>=0.0.1" ]