From b844acf061facdd81f8fa7bb48931b85cdb17e01 Mon Sep 17 00:00:00 2001 From: Jovan Mitrevski Date: Tue, 5 Nov 2024 11:37:22 -0600 Subject: [PATCH] restructure of existing documentation --- docs/{ => advanced}/command.rst | 2 +- docs/{ => advanced}/flows.rst | 0 docs/advanced/oneapi.rst | 16 +++---- docs/{ => api}/details.rst | 0 docs/index.rst | 10 +++-- docs/setup.rst | 75 +++++++++++++++++---------------- 6 files changed, 53 insertions(+), 50 deletions(-) rename docs/{ => advanced}/command.rst (97%) rename docs/{ => advanced}/flows.rst (100%) rename docs/{ => api}/details.rst (100%) diff --git a/docs/command.rst b/docs/advanced/command.rst similarity index 97% rename from docs/command.rst rename to docs/advanced/command.rst index cb9d346e31..67f7e3fe2f 100644 --- a/docs/command.rst +++ b/docs/advanced/command.rst @@ -50,7 +50,7 @@ hls4ml config hls4ml config [-h] [-m MODEL] [-w WEIGHTS] [-o OUTPUT] -This creates a conversion configuration file. Visit Configuration section of the :doc:`Setup ` page for more details on how to write a configuration file. +This creates a conversion configuration file. Visit Configuration section of the :doc:`Setup <../setup>` page for more details on how to write a configuration file. **Arguments** diff --git a/docs/flows.rst b/docs/advanced/flows.rst similarity index 100% rename from docs/flows.rst rename to docs/advanced/flows.rst diff --git a/docs/advanced/oneapi.rst b/docs/advanced/oneapi.rst index ae0e0bc56b..fb926409eb 100644 --- a/docs/advanced/oneapi.rst +++ b/docs/advanced/oneapi.rst @@ -3,18 +3,17 @@ oneAPI Backend ============== The ``oneAPI`` backend of hls4ml is designed for deploying NNs on Intel/Altera FPGAs. It will eventually -replace the ``Quartus`` backend, which should really have been called the Intel HLS backend. (The actual Quartus -program continues to be used with IP produced by the ``oneAPI`` backend.) -This section discusses details of the ``oneAPI`` backend. +replace the ``Quartus`` backend, which targeted Intel HLS. (Quartus continues to be used with IP produced by the +``oneAPI`` backend.) This section discusses details of the ``oneAPI`` backend. The ``oneAPI`` code uses SYCL kernels to implement the logic that is deployed on FPGAs. It naturally leads to the -accelerator style of programming. In the IP Component flow, which is currently the only flow supported, the +accelerator style of programming. In the SYCL HLS (IP Component) flow, which is currently the only flow supported, the kernel becomes the IP, and the "host code" becomes the testbench. An accelerator flow, with easier deployment on PCIe accelerator boards, is planned to be added in the future. The produced work areas use cmake to build the projects in a style based `oneAPI-samples `_. -The standard ``fpga_emu``, ``report``, ``fpga_sim``, and ``fpga`` are supported. Additionally, ``make lib`` +The standard ``fpga_emu``, ``report``, ``fpga_sim``, and ``fpga`` make targets are supported. Additionally, ``make lib`` produces the library used for calling the ``predict`` function from hls4ml. The ``compile`` and ``build`` commands in hls4ml interact with the cmake system, so one does not need to manually use the build system, but it there if desired. @@ -30,6 +29,7 @@ io_parallel and io_stream As mentioned in the :ref:`I/O Types` section, ``io_parallel`` is for small models, while ``io_stream`` is for larger models. In ``oneAPI``, there is an additional difference: ``io_stream`` implements each layer on its own ``task_sequence``. Thus, the layers run in parallel, with pipes connecting the inputs and outputs. This -is similar in style to the `dataflow` implementation on Vitis, but more explicit. On the other hand, ``io_parallel`` -always uses a single task, relying on pipelining within the task for good performance. In contrast, the Vitis -backend sometimes uses dataflow with ``io_parallel``. +is similar in style to the `dataflow` implementation on Vitis HLS, but more explicit. It is also a change +relative to the Intel HLS-based ``Quartus`` backend. On the other hand, ``io_parallel`` always uses a single task, +relying on pipelining within the task for good performance. In contrast, the Vitis backend sometimes uses dataflow +with ``io_parallel``. diff --git a/docs/details.rst b/docs/api/details.rst similarity index 100% rename from docs/details.rst rename to docs/api/details.rst diff --git a/docs/index.rst b/docs/index.rst index 339c4cfd42..2e417b1d74 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,9 +6,6 @@ status setup release_notes - details - flows - command reference .. toctree:: @@ -16,18 +13,23 @@ :glob: :caption: Quick API Reference - api/* + api/configuration + api/details + api/hls-model + api/profiling .. toctree:: :hidden: :caption: Advanced Features + advanced/flows advanced/qonnx advanced/fifo_depth advanced/extension advanced/oneapi advanced/accelerator advanced/model_optimization + advanced/command .. toctree:: :hidden: diff --git a/docs/setup.rst b/docs/setup.rst index d083e07c71..628f4ee69a 100644 --- a/docs/setup.rst +++ b/docs/setup.rst @@ -107,76 +107,77 @@ Done! You've built your first project using ``hls4ml``! To learn more about our If you want to configure your model further, check out our :doc:`Configuration ` page. -Apart from our main API, we also support model conversion using a command line interface, check out our next section to find out more: +.. + Apart from our main API, we also support model conversion using a command line interface, check out our next section to find out more: -Getting started with hls4ml CLI (deprecated) --------------------------------------------- + Getting started with hls4ml CLI (deprecated) + -------------------------------------------- -As an alternative to the recommended Python PI, the command-line interface is provided via the ``hls4ml`` command. + As an alternative to the recommended Python PI, the command-line interface is provided via the ``hls4ml`` command. -To follow this tutorial, you must first download our ``example-models`` repository: + To follow this tutorial, you must first download our ``example-models`` repository: -.. code-block:: bash + .. code-block:: bash - git clone https://github.com/fastmachinelearning/example-models + git clone https://github.com/fastmachinelearning/example-models -Alternatively, you can clone the ``hls4ml`` repository with submodules + Alternatively, you can clone the ``hls4ml`` repository with submodules -.. code-block:: bash + .. code-block:: bash - git clone --recurse-submodules https://github.com/fastmachinelearning/hls4ml + git clone --recurse-submodules https://github.com/fastmachinelearning/hls4ml -The model files, along with other configuration parameters, are defined in the ``.yml`` files. -Further information about ``.yml`` files can be found in :doc:`Configuration ` page. + The model files, along with other configuration parameters, are defined in the ``.yml`` files. + Further information about ``.yml`` files can be found in :doc:`Configuration ` page. -In order to create an example HLS project, first go to ``example-models/`` from the main directory: + In order to create an example HLS project, first go to ``example-models/`` from the main directory: -.. code-block:: bash + .. code-block:: bash - cd example-models/ + cd example-models/ -And use this command to translate a Keras model: + And use this command to translate a Keras model: -.. code-block:: bash + .. code-block:: bash - hls4ml convert -c keras-config.yml + hls4ml convert -c keras-config.yml -This will create a new HLS project directory with an implementation of a model from the ``example-models/keras/`` directory. -To build the HLS project, do: + This will create a new HLS project directory with an implementation of a model from the ``example-models/keras/`` directory. + To build the HLS project, do: -.. code-block:: bash + .. code-block:: bash - hls4ml build -p my-hls-test -a + hls4ml build -p my-hls-test -a -This will create a Vivado HLS project with your model implementation! + This will create a Vivado HLS project with your model implementation! -**NOTE:** For the last step, you can alternatively do the following to build the HLS project: + **NOTE:** For the last step, you can alternatively do the following to build the HLS project: -.. code-block:: Bash + .. code-block:: Bash - cd my-hls-test - vivado_hls -f build_prj.tcl + cd my-hls-test + vivado_hls -f build_prj.tcl -``vivado_hls`` can be controlled with: + ``vivado_hls`` can be controlled with: -.. code-block:: bash + .. code-block:: bash - vivado_hls -f build_prj.tcl "csim=1 synth=1 cosim=1 export=1 vsynth=1" + vivado_hls -f build_prj.tcl "csim=1 synth=1 cosim=1 export=1 vsynth=1" -Setting the additional parameters from ``1`` to ``0`` disables that step, but disabling ``synth`` also disables ``cosim`` and ``export``. + Setting the additional parameters from ``1`` to ``0`` disables that step, but disabling ``synth`` also disables ``cosim`` and ``export``. -Further help -^^^^^^^^^^^^ + Further help + ^^^^^^^^^^^^ -* For further information about how to use ``hls4ml``\ , do: ``hls4ml --help`` or ``hls4ml -h`` -* If you need help for a particular ``command``\ , ``hls4ml command -h`` will show help for the requested ``command`` -* We provide a detailed documentation for each of the command in the :doc:`Command Help <../command>` section + * For further information about how to use ``hls4ml``\ , do: ``hls4ml --help`` or ``hls4ml -h`` + * If you need help for a particular ``command``\ , ``hls4ml command -h`` will show help for the requested ``command`` + * We provide a detailed documentation for each of the command in the :doc:`Command Help ` section Existing examples ----------------- -* Examples of model files and weights can be found in `example_models `_ directory. * Training codes and examples of resources needed to train the models can be found in the `tutorial `__. +* Examples of model files and weights can be found in `example_models `_ directory. Uninstalling ------------