Altera HLS compatibility

[bugracyln]

Description

📝 Please include a summary of the change.
Added compatibility for the new Altera HLS compiler. It is a simple fix and keeps hls4ml backwards compatible with the old oneAPI.

Type of change

• Bug fix (non-breaking change that fixes an issue)
• Documentation update
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• A new research paper code implementation
• Other (Specify)

Tests

📝 Please describe the tests that you ran to verify your changes.
Tested multiple compiles with both icpx and ahls compilers. Note that any new addition to the oneAPI backend, if using new libraries, requires consideration regarding the naming convention since the ahls compiler uses 'altera' instead of 'intel'.

Test Configuration:
N/A

Checklist

• I have read the guidelines for contributing.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.
• I have installed and run pre-commit on the files I edited or added.
• I have added tests that prove my fix is effective or that my feature works.

[JanFSchulte]

Thanks a lot! Looks good to me, with some minor nitpicks.

Please also update the documentation. I think we basically need to replace oneAPI in https://github.com/fastmachinelearning/hls4ml/blob/main/docs/backend/oneapi.rst with a oneAPI/Altera HLS in all cases. Then the status page https://github.com/fastmachinelearning/hls4ml/blob/main/docs/intro/status.rst also needs to be updated to reflect that we support Altera HLS.

[JanFSchulte]

Thinking about it a bit more, do we need to update the report parsing code to adapt to any changes, or does Altera HLS keep the formats compatible. Also should we add additional tests in the CI for Altera HLS? In many ways those would be redundant with oneAPI, but maybe add a dedicated test just for Altera HLS compilation?

[jmitrevs]

I requested the pytests to run to make sure we don't break anything. For testing with the Altera compiler, I think we need a new docker container. My guess is that we will transition fairly quickly because it seems like oneAPI 2025.0 is hard to get now.

[Copilot]

Pull request overview

Adds Altera HLS (“ahls”) compatibility to the oneAPI backend by introducing an AHLS compile-time switch and updating SYCL extension namespaces/includes accordingly, while aiming to keep compatibility with existing Intel oneAPI (icpx) flows.

Changes:

• Add AHLS-gated includes/namespaces for SYCL FPGA extensions, selectors, and experimental properties in oneAPI C++ templates.
• Update the oneAPI template CMake to pick icpx or ahls and define AHLS when ahls is used.
• Add an icpx → ahls fallback in the Python oneAPI backend build check, and adjust pipe namespace generation in oneAPI type code.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
hls4ml/templates/oneapi/myproject_test.cpp	Switch SYCL FPGA extension include and selector namespace based on AHLS.
hls4ml/templates/oneapi/myproject_bridge.cpp	Use Altera vs Intel emulator selector depending on AHLS.
hls4ml/templates/oneapi/firmware/nnet_utils/nnet_common.h	Switch ac_types include paths based on AHLS.
hls4ml/templates/oneapi/firmware/myproject.h	Gate experimental property namespaces (ready_latency, streaming_interface, pipelined) on AHLS.
hls4ml/templates/oneapi/firmware/myproject.cpp	Gate task_sequence include and alias on AHLS.
hls4ml/templates/oneapi/firmware/defines.h	Switch core SYCL/AC type extension includes based on AHLS.
hls4ml/templates/oneapi/CMakeLists.txt	Select icpx or ahls on UNIX and define AHLS for ahls builds.
hls4ml/backends/oneapi/oneapi_types.py	Change generated pipe namespace selection logic (currently tied to ahls presence in PATH).
hls4ml/backends/oneapi/oneapi_backend.py	Add build-time fallback check for ahls when icpx isn’t found.

Suppressed comments (1)

hls4ml/backends/oneapi/oneapi_types.py:212

• Same issue as above: selecting altera vs intel via shutil.which('ahls') in Python can disagree with the actual compiler chosen by CMake, producing C++ that won’t compile in mixed installations. Emit an #ifdef AHLS-guarded namespace in the generated C++ instead.

    def declare_cpp(self, indent=''):
        compiler_name = 'altera' if shutil.which('ahls') else 'intel'
        lines = indent + f'class {self.pipe_id};\n'
        lines += indent + (
            f'using {self.pipe_name} = sycl::ext::{compiler_name}::experimental::pipe<{self.pipe_id}, '
            + f'{self.type.name}, {self.pragma[-1]}>;\n'

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jmitrevs]

The test failures look unrelated.

[JanFSchulte]

Thanks, looks good to me now. The remaining question is the test coverage. My understanding is that it would take some effort to add Altera HLS to the setup, so we need to decide if we want to wait for that, or merge this already and add tests later.

[vloncar]

Why does it stop short of renaming the backend? The changes make it incompatible with previous releases of oneAPI and the product doesn't seem to be advertised as related to oneAPI on Altera website so it just adds confusion to the user who don't care about technology on which the product is built.

[JanFSchulte]

My understanding is that this keeps compatibility with oneAPI 2025.0? So I wouldn't drop oneAPI from the docs, but we could change it to describe AHLS independent of oneAPI, independent of how they are basically the same in the backend.

[vloncar]

It's a bit confusing. If I want to use it, what should I put in backend="..."? The names of the backends used to correspond to the name in the document. Now there's "Altera HLS IP Gen" as well, but this is not accepted. The answer remains oneAPI. Then in the feature matrix table we have them split, implying there's two, but Altera is not reachable standalone. The compatibility is threaded through the code through the compiler check, but Altera overrides the oneAPI compiler. I don't know if we have oneAPI users, but imagine you're one, and you want to port your code. You actually have to have completely separate environments (and we've seen that containerizing was troublesome unless you're really a master of these toolkits) despite these being two products that don't clash. Just having ahls installed makes it impossible to run anything against oneAPI 2025.0 yet you still have to use that name in conversion scripts.

[JanFSchulte]

I overlooked the part with the conversion. I agree that it should be separate there as well so that you pass altera or something like it as the backend argument. As for the environments, I guess that's not solvable by us, but I think that communicating that these are different tools that need separate installations in the docs might help.

[vloncar]

Regarding environments, it's not for us to solve, but we're creating a problem. Only because of the way the check is implemented is this an issue. Far simpler solution would be to have OneAPIBackend define a variable compiler_name set to icpx. Then build() looks for whatever that is. On top, add a very light AlteraBackend that changes only the backend name and the compiler_name. This can then be passed down to CMake to look for only one. Keep the changes to .h files as is. It's not 100% clean because of the .h files, but makes it easy to unify and remove oneAPI in next release. That way two backends exist, and are easily switchable between them. We don't touch the environment but also don't force the separate environment.

[jmitrevs]

We don't want a very light AlteraBackend. If anything, it's the oneAPI backend that should be light. Otherwise, we are stuck with what we have now with the Vitis/Vivado situation. It doesn't seem like you can even install oneAPI 2025.0 any more.

[jmitrevs]

There was a suggestion from the Altera folks to rename the backend, by the way. I think it was not included in this to be less disruptive.

[vloncar]

Agree with that. So it's the Altera one that is the main, and oneAPI is the light wrapper that gets removed eventually.

[jmitrevs]

Do you think it's worth the effort to make a whole new backend just for a compiler name change plus some include paths and namespaces?

[jmitrevs]

Doesn't Altera HLS refer to the old Intel HLS, currently deprecated. It seems like the name is Altera HLS IP Gen, right? There is discussion on whether it should be a separate backend from oneAPI or if these should be one, as the code has it now. The documentation should follow the code, whatever we decide. I would also remove the experimental, and add (deprecated) to Intel HLS.

[vloncar]

I don't think it is a whole new backend. It sounds large but is three simple stages (on top of what's already done):

1. Rename: existing OneAPIBackend to AlteraBackend (that's just a class rename, filename rename and name property within AlteraBackend), the folder and types, register in backends init. This is "large" only in a sense that it touches a few files, but is not a burden to review.
2. Passing compiler name: In AlteraBackend add self.compiler_name = 'ahls', ensure that is used for f'which {self.compiler_name}' check (no fallbacks to icpx), and furthermore passed to CMakeLists.txt (via writer or other means).
3. Create a new backend OneAPIBackend(AlteraBackend) and in its init just override name and compiler_name. Register that backend and we're set.

Everything should work as before, including any tests. When the time comes, it's just a matter of deleting the oneAPI backend class and we can remove the compiler_name.

[jmitrevs]

I am fine with that proposal. I think AI can pretty quickly change the file names and class types for part 1, like OneAPIACTypeConverter. We should not try to do it manually.

[jmitrevs]

This is replaced by #1533

[jmitrevs]

Reopening just to run pytests. (DO NOT MERGE.)