Add hex-native convolution support via keras-hexagdly

[YugnatD]

Summary

IACT cameras (LST-1, MAGIC, MST NectarCam/FlashCam, etc.) have hexagonal
pixel grids, but CTLearn's model backbones only support square convolutions
(keras.layers.Conv2D), so dl1_data_handler's ImageMapper interpolates
every hex camera image onto an axis-aligned square grid (BilinearMapper
and friends) before it ever reaches the network.

This PR adds a hex-native alternative built on
keras-hexagdly:
HexagdlyMapper places each pixel at its exact grid cell (no interpolation)
on the addressing grid keras_hexagdly.layers.Conv2d/MaxPool2d expect,
and HexCNN is a CTLearnModel backbone built on those layers.

Both plug into CTLearn's existing factories
(image_mapper_type=HexagdlyMapper, model_type=HexCNN) with zero
changes to dl1_data_handler or to CTLearn's config system --
ImageMapper.from_name/CTLearnModel.from_name resolve them via plain
subclass discovery once imported.

Why this matters beyond model architecture: FPGA-native inference

keras-hexagdly supports exporting Conv2d/MaxPool2d (io_stream)
directly to FPGA via hls4ml, synthesizing the hexagonal convolution itself
in hardware. This is not just a modeling nicety -- it removes a hard
blocker for CTA's real-time / edge-inference use cases:

• Today, every hex camera goes through BilinearMapper (or another
  interpolation mapper) before a model ever sees it. That resampling step
  has no FPGA synthesis path, so an interpolate-to-square model cannot be
  deployed as a single FPGA pipeline from raw camera data.
• With HexagdlyMapper, there is no interpolation step to begin with --
  HexCNN operates on the camera's native geometry, so the whole
  pipeline (mapping + convolution + pooling) becomes FPGA-synthesizable,
  opening the door to low-latency, on-site hex-native inference that
  the square path structurally cannot offer.

This is the main reason to care about this PR beyond "an alternative
architecture to try": it's a prerequisite for FPGA-based hex-native
inference in CTLearn at all.

What's added

• ctlearn/core/hexagdly_geometry.py -- HexGridTransform: maps any
  hexagonal ctapipe.CameraGeometry (including rotated cameras like LST-1)
  onto keras-hexagdly's offset-column grid, with an auto de-rotation step
  and a neighbour-graph consistency check.
• ctlearn/core/hexagdly_mapper.py -- HexagdlyMapper(ImageMapper).
• ctlearn/core/hexagdly_model.py -- HexCNN(CTLearnModel), mirrors
  SingleCNN.
• Guarded imports in train_model.py / predict_model.py /
  predict_LST1.py so the new classes are actually discoverable through the
  CLI tools once keras-hexagdly is installed -- a no-op otherwise.
• New optional hexagdly extra in pyproject.toml
  (pip install ctlearn[hexagdly]) -- no new dependency for anyone who
  doesn't opt in.
• Tests in ctlearn/core/tests/test_hexagdly_*.py: fast/offline using the
  bundled LST-1 resource, plus --remote-data-gated checks against
  MAGICCam/NectarCam/FlashCam/CHEC/SCTCam.
• benchmarks/hexcnn_vs_singlecnn_lst1_energy.py +
  benchmarks/results/ -- see below.

Benchmark (honest caveat)

Ran HexCNN+HexagdlyMapper vs. SingleCNN+BilinearMapper on LST-1
energy regression through the real TrainCTLearnModel tool -- see
benchmarks/results/. Both train end-to-end with no special-casing, at
comparable wall-clock cost. The only dataset available in this environment
is ctapipe's small CI test file (~70 images from ~18-19 events), too small
for a real accuracy claim, and the raw loss numbers currently favor
SingleCNN for an explainable reason (an untuned initializer-scale
mismatch between the two libraries' defaults, detailed in the report -- not
evidence the hex path underperforms). A real accuracy comparison needs
production-scale data this environment doesn't have access to.

Also found, not fixed here

SingleCNN's default attention_mechanism ("Dual-SE") crashes
immediately with KeyError: 'ratio' -- ctlearn/core/model.py reads
self.attention["ratio"], but CTLearnModel.__init__ only ever sets
"reduction_ratio". Pre-existing and unrelated to this PR (HexCNN and
ResNet both correctly use "reduction_ratio"). Happy to open a separate
tiny fix for it if useful.

Testing

```
pytest ctlearn/core/tests/test_hexagdly_.py -v # offline
pytest ctlearn/core/tests/test_hexagdly_.py --remote-data=any # + other cameras
```

[tjarkmiener]

Hi @YugnatD! Thank you so much for this important and interesting work! I posted some comments. As said in the comments everything related to the geometry and mapping should be moved to the corresponding modules of the dl1dh. Besides currently the tools are missing a check that validates the configuration, i.e. when HexagdlyMapper is selected the Conv2D import has to be from hgly and vice versa.

[tjarkmiener]

Since this is a new subclass of the ImageMapper, I'd prefer to move HexagdlyMapper to the dl1_data_handler.image_mapper modules.

[tjarkmiener]

The same as HexagdlyMapper, I'd prefer to the HexGridTransform to the corresponding dl1dh module.

[tjarkmiener]

Is this line (import of a different Conv2D implementation) the only difference between HexCNN and SingleCNN? If so, I would suggestion to add a new config traits to the existing SingleCNN which specify the Conv2D import. That would remove quite a lot of code reputation. In principle the scheme can be also added to the ResNet model.

[tjarkmiener]

Here and elsewhere: If we move it to the dl1dh we should bump the version and do not make it optional.

[tjarkmiener]

If it's available on pypi we can just add it to the normal dependencies I guess.

[YugnatD]

Hi @YugnatD! Thank you so much for this important and interesting work! I posted some comments. As said in the comments everything related to the geometry and mapping should be moved to the corresponding modules of the dl1dh. Besides currently the tools are missing a check that validates the configuration, i.e. when HexagdlyMapper is selected the Conv2D import has to be from hgly and vice versa.

Thanks @tjarkmiener for the review, im currently modiyfing it and will soon make a pr to dl1dh to split the implemetation as you asked.

But While working on this I had the thought that data augmentation could silently break things for the hex path, and noticed #282 ("Add data augmentation") is open. So I'm wondering: is augmentation actually planned/being worked on, and how should I take that into account here?

I dug a bit and found an old prototype (ctlearn/core/data_loader/base_loader.py, referenced from that issue but not on any current branch) that implements flip/rotate/translate augmentation via cv2.warpAffine directly on the post-mapping (H, W, C) image array.

That approach works fine for the square-mapped path, but it won't be safe for HexagdlyMapper's output once/if this PR lands: cell adjacency there depends on column parity, so rotating or flipping the mapped array scrambles which cells the hex convolution treats as physical neighbors — not just interpolation blur like it would be for a square grid, but a geometrically wrong input that still looks well-formed. A hex-lattice rotation/reflection needs to be applied before mapping (at the pixel/geometry level) or worked out in axial coordinates and re-converted through the same offset-column addressing, not applied to the mapped array directly.

Do you want me to guard against this in this PR (e.g. reject or restrict augmentation when conv_backend="hexagdly"), or is it fine to leave alone for now and handle it properly once augmentation actually gets implemented?