triggerflow 0.1.4__tar.gz

triggerflow-0.1.4/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: triggerflow
+Version: 0.1.4
+Summary: Utilities for ML models targeting hardware triggers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mlflow>=2.0
+
+# Machine Learning for Hardware Triggers
+
+`triggerflow` provides a set of utilities for Machine Learning models targeting FPGA deployment. 
+The `TriggerModel` class consolidates several Machine Learning frontends and compiler backends to construct a "trigger model". MLflow utilities are for logging, versioning, and loading of trigger models.
+
+## Installation
+
+```bash
+pip install triggerflow
+```
+
+## Usage
+
+```python
+
+from triggerflow.core import TriggerModel 
+
+trigger_model = TriggerModel(name="my-trigger-model", ml_backend="Keras", compiler="hls4ml", model, compiler_config or None)
+trigger_model() # call the constructor
+
+# then:
+output_software = trigger_model.software_predict(input_data)
+output_firmware = trigger_model.firmware_predict(input_data)
+output_qonnx = trigger_model.qonnx_predict(input_data)
+
+# save and load trigger models:
+trigger_model.save("trigger_model.tar.xz")
+
+# in a separate session:
+from trigger_model.core import TriggerModel 
+trigger_model = TriggerModel.load("trigger_model.tar.xz")
+```
+
+## Logging with MLflow
+
+```python
+# logging with MLFlow:
+import mlflow
+from trigger_model.mlflow_wrapper import log_model
+
+mlflow.set_tracking_uri("https://ngt.cern.ch/models")
+experiment_id = mlflow.create_experiment("example-experiment")
+
+with mlflow.start_run(run_name="trial-v1", experiment_id=experiment_id):
+    log_model(trigger_model, registered_model_name="TriggerModel")
+```
+
+### Note: This package doesn't install dependencies so it won't disrupt specific training environments or custom compilers. For a reference environment, see `environment.yml`.
+
+

triggerflow-0.1.4/README.md

@@ -0,0 +1,50 @@
+# Machine Learning for Hardware Triggers
+
+`triggerflow` provides a set of utilities for Machine Learning models targeting FPGA deployment. 
+The `TriggerModel` class consolidates several Machine Learning frontends and compiler backends to construct a "trigger model". MLflow utilities are for logging, versioning, and loading of trigger models.
+
+## Installation
+
+```bash
+pip install triggerflow
+```
+
+## Usage
+
+```python
+
+from triggerflow.core import TriggerModel 
+
+trigger_model = TriggerModel(name="my-trigger-model", ml_backend="Keras", compiler="hls4ml", model, compiler_config or None)
+trigger_model() # call the constructor
+
+# then:
+output_software = trigger_model.software_predict(input_data)
+output_firmware = trigger_model.firmware_predict(input_data)
+output_qonnx = trigger_model.qonnx_predict(input_data)
+
+# save and load trigger models:
+trigger_model.save("trigger_model.tar.xz")
+
+# in a separate session:
+from trigger_model.core import TriggerModel 
+trigger_model = TriggerModel.load("trigger_model.tar.xz")
+```
+
+## Logging with MLflow
+
+```python
+# logging with MLFlow:
+import mlflow
+from trigger_model.mlflow_wrapper import log_model
+
+mlflow.set_tracking_uri("https://ngt.cern.ch/models")
+experiment_id = mlflow.create_experiment("example-experiment")
+
+with mlflow.start_run(run_name="trial-v1", experiment_id=experiment_id):
+    log_model(trigger_model, registered_model_name="TriggerModel")
+```
+
+### Note: This package doesn't install dependencies so it won't disrupt specific training environments or custom compilers. For a reference environment, see `environment.yml`.
+
+

triggerflow-0.1.4/pyproject.toml

@@ -0,0 +1,24 @@
+[build-system]
+requires = ["setuptools>=65.5", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "triggerflow"
+version = "0.1.4"
+description = "Utilities for ML models targeting hardware triggers"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "mlflow>=2.0"
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent"
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"triggerflow" = ["templates/*"]

triggerflow-0.1.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

triggerflow-0.1.4/src/triggerflow/core.py

@@ -0,0 +1,550 @@
+from pathlib import Path
+import json
+import numpy as np
+import tarfile
+import importlib
+from abc import ABC, abstractmethod
+from typing import Optional, Dict, Any, Union
+import shutil, warnings
+import importlib.resources as pkg_resources
+import triggerflow.templates 
+
+
+class ModelConverter(ABC):
+    """Abstract base class for model converters"""
+    
+    @abstractmethod
+    def convert(self, model, workspace: Path, **kwargs) -> Optional[Path]:
+        """Convert model to intermediate format"""
+        pass
+
+
+class CompilerStrategy(ABC):
+    """Abstract base class for compilation strategies"""
+    
+    @abstractmethod
+    def compile(self, model, workspace: Path, config: Optional[Dict] = None,  **kwargs) -> Any:
+        """Compile model to firmware"""
+        pass
+    
+    @abstractmethod
+    def load_compiled_model(self, workspace: Path) -> Any:
+        """Load a previously compiled model"""
+        pass
+
+
+class ModelPredictor(ABC):
+    """Abstract base class for model predictors"""
+    
+    @abstractmethod
+    def predict(self, input_data: np.ndarray) -> np.ndarray:
+        """Make predictions using the model"""
+        pass
+
+
+class KerasToQONNXConverter(ModelConverter):
+    """Converts Keras models to QONNX format"""
+    
+    def convert(self, model, workspace: Path, **kwargs) -> Path:
+        import tensorflow as tf
+        from qonnx.converters import keras as keras_converter
+        from qonnx.core.modelwrapper import ModelWrapper
+        from qonnx.transformation.channels_last import ConvertToChannelsLastAndClean
+        from qonnx.transformation.gemm_to_matmul import GemmToMatMul
+        from qonnx.util.cleanup import cleanup_model
+        
+        qonnx_path = workspace / "model_qonnx.onnx"
+        input_signature = [tf.TensorSpec(1, model.inputs[0].dtype, name="input_0")]
+        qonnx_model, _ = keras_converter.from_keras(model, input_signature, output_path=qonnx_path)
+        qonnx_model = ModelWrapper(qonnx_model)
+        qonnx_model = cleanup_model(qonnx_model)
+        qonnx_model = qonnx_model.transform(ConvertToChannelsLastAndClean())
+        qonnx_model = qonnx_model.transform(GemmToMatMul())
+        cleaned_model = cleanup_model(qonnx_model)
+        
+        return qonnx_path, cleaned_model
+
+
+class NoOpConverter(ModelConverter):
+    """No-operation converter for models that don't need conversion"""
+    
+    def convert(self, model, workspace: Path, **kwargs) -> Optional[Path]:
+        return None
+
+
+class HLS4MLStrategy(CompilerStrategy):
+    """HLS4ML compilation strategy for Keras models"""
+    
+    def compile(self, model, workspace: Path, config: Optional[Dict] = None, **kwargs) -> Any:
+        import hls4ml
+        
+        firmware_dir = workspace / "firmware"
+        firmware_dir.mkdir(exist_ok=True)
+        
+        cfg = config or hls4ml.utils.config_from_keras_model(model, granularity="name")
+
+        hls_kwargs = {
+            "hls_config": cfg,
+            "output_dir": str(firmware_dir),
+            "io_type": "io_stream",
+            "backend": "Vitis"
+        }
+        hls_kwargs.update(kwargs)
+
+        firmware_model = hls4ml.converters.convert_from_keras_model(
+            model,
+            **hls_kwargs
+        )
+
+        firmware_model.compile()
+        if shutil.which("vivado") is not None:
+             firmware_model.build()
+        else:
+            warnings.warn("Vivado not found in PATH. Firmware build failed.", UserWarning)
+        firmware_model.save(workspace / "firmware_model.fml")
+        return firmware_model
+    
+    def load_compiled_model(self, workspace: Path) -> Any:
+        from hls4ml.converters import link_existing_project
+        
+        firmware_model = link_existing_project(workspace / "firmware")
+        firmware_model.compile()
+        return firmware_model
+
+
+class ConiferStrategy(CompilerStrategy):
+    """Conifer compilation strategy for XGBoost models"""
+    
+    def compile(self, model, workspace: Path, config: Optional[Dict] = None) -> Any:
+        import conifer
+        
+        firmware_dir = workspace / "firmware"
+        firmware_dir.mkdir(exist_ok=True)
+        
+        cfg = config or conifer.backends.xilinxhls.auto_config()
+        firmware_model = conifer.converters.convert_from_xgboost(
+            model,
+            config=cfg,
+            output_dir=str(firmware_dir)
+        )
+        firmware_model.compile()
+        if shutil.which("vivado") is not None:
+             firmware_model.build()
+        else:
+            warnings.warn("Vivado not found in PATH. Firmware build failed.", UserWarning)
+        firmware_model.save(workspace / "firmware_model.fml")
+        return firmware_model
+    
+    def load_compiled_model(self, workspace: Path) -> Any:
+        from conifer import load_model
+        
+        firmware_model = load_model(workspace / "firmware_model.fml")
+        firmware_model.compile()
+        return firmware_model
+
+
+class DA4MLStrategy(CompilerStrategy):
+    """DA4ML compilation strategy (placeholder)"""
+    
+    def compile(self, model, workspace: Path, config: Optional[Dict] = None) -> Any:
+        raise NotImplementedError("DA4ML conversion without QONNX not yet implemented")
+    
+    def load_compiled_model(self, workspace: Path) -> Any:
+        raise NotImplementedError("DA4ML loading not yet implemented")
+
+
+class FINNStrategy(CompilerStrategy):
+    """FINN compilation strategy (placeholder)"""
+    
+    def compile(self, model, workspace: Path, config: Optional[Dict] = None) -> Any:
+        raise NotImplementedError("FINN conversion without QONNX not yet implemented")
+    
+    def load_compiled_model(self, workspace: Path) -> Any:
+        raise NotImplementedError("FINN loading not yet implemented")
+
+
+class SoftwarePredictor(ModelPredictor):
+    """Software-based model predictor"""
+    
+    def __init__(self, model, backend: str):
+        self.model = model
+        self.backend = backend.lower()
+    
+    def predict(self, input_data):
+        if input_data.ndim == 1:
+            input_data = np.expand_dims(input_data, axis=0)
+        return self.model.predict(input_data)
+
+
+class QONNXPredictor(ModelPredictor):
+    """QONNX-based model predictor"""
+    
+    def __init__(self, qonnx_model, input_name: str):
+        self.qonnx_model = qonnx_model
+        self.input_name = input_name
+    
+    def predict(self, input_data: np.ndarray) -> np.ndarray:
+        from qonnx.core.onnx_exec import execute_onnx
+        
+        input_data = np.asarray(input_data)
+        if input_data.ndim == 1:
+            input_data = np.expand_dims(input_data, axis=0)
+        
+        outputs = []
+        for i in range(input_data.shape[0]):
+            sample = input_data[i].astype("float32").reshape(1, -1)
+            output_dict = execute_onnx(self.qonnx_model, {self.input_name: sample})
+            outputs.append(output_dict["global_out"])
+        
+        return np.vstack(outputs)
+
+
+class FirmwarePredictor(ModelPredictor):
+    """Firmware-based model predictor"""
+    
+    def __init__(self, firmware_model):
+        if firmware_model is None:
+            raise RuntimeError("Firmware model not built.")
+        self.firmware_model = firmware_model
+    
+    def predict(self, input_data: np.ndarray) -> np.ndarray:
+        return self.firmware_model.predict(input_data)
+
+
+class ConverterFactory:
+    """Factory for creating model converters"""
+    
+    @staticmethod
+    def create_converter(ml_backend: str, compiler: str) -> ModelConverter:
+        if ml_backend.lower() == "keras" and compiler.lower() == "hls4ml":
+            return KerasToQONNXConverter()
+        else:
+            return NoOpConverter()
+
+
+class CompilerFactory:
+    """Factory for creating compilation strategies"""
+    
+    @staticmethod
+    def create_compiler(ml_backend: str, compiler: str) -> CompilerStrategy:
+        backend = ml_backend.lower()
+        comp = compiler.lower()
+        
+        if backend == "keras" and comp == "hls4ml":
+            return HLS4MLStrategy()
+        elif backend == "xgboost" and comp == "conifer":
+            return ConiferStrategy()
+        elif comp == "da4ml":
+            return DA4MLStrategy()
+        elif comp == "finn":
+            return FINNStrategy()
+        else:
+            raise RuntimeError(f"Unsupported combination: ml_backend={backend}, compiler={comp}")
+
+
+class WorkspaceManager:
+    """Manages workspace directories and metadata"""
+    
+    BASE_WORKSPACE = Path.cwd() / "triggermodel"
+    
+    def __init__(self):
+        self.workspace = self.BASE_WORKSPACE
+        self.artifacts = {"firmware": None}
+        self.metadata = {
+            "name": None,
+            "ml_backend": None,
+            "compiler": None,
+            "versions": []
+        }
+    
+    def setup_workspace(self, name: str, ml_backend: str, compiler: str):
+        """Initialize workspace and metadata"""
+        self.workspace.mkdir(parents=True, exist_ok=True)
+        self.metadata.update({
+            "name": name,
+            "ml_backend": ml_backend,
+            "compiler": compiler,
+        })
+    
+    def save_native_model(self, model, ml_backend: str):
+        """Save the native model to workspace"""
+        if ml_backend.lower() == "keras":
+            model.save(self.workspace / "keras_model")
+        elif ml_backend.lower() == "xgboost":
+            model.save_model(str(self.workspace / "xgb_model.json"))
+    
+    def add_artifact(self, key: str, value: Any):
+        """Add artifact to tracking"""
+        self.artifacts[key] = value
+    
+    def add_version(self, version_info: Dict):
+        """Add version information"""
+        self.metadata["versions"].append(version_info)
+    
+    def save_metadata(self):
+        """Save metadata to file"""
+        with open(self.workspace / "metadata.json", "w") as f:
+            json.dump({
+                "name": self.metadata["name"],
+                "ml_backend": self.metadata["ml_backend"],
+                "compiler": self.metadata["compiler"],
+            }, f, indent=2)
+
+
+class ModelSerializer:
+    """Handles model serialization and deserialization"""
+    
+    @staticmethod
+    def save(workspace: Path, path: str):
+        """Serialize the workspace into a tar.xz archive"""
+        path = Path(path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tarfile.open(path, mode="w:xz") as tar:
+            tar.add(workspace, arcname=workspace.name)
+        print(f"TriggerModel saved to {path}")
+    
+    @staticmethod
+    def load(path: str) -> Dict[str, Any]:
+        """Load workspace from tar.xz archive"""
+        path = Path(path)
+        if not path.exists():
+            raise FileNotFoundError(f"{path} does not exist")
+        
+        workspace = Path.cwd() / "triggermodel"
+        
+        if workspace.exists():
+            response = input(f"{workspace} already exists. Overwrite? [y/N]: ").strip().lower()
+            if response != "y":
+                print("Load cancelled by user.")
+                return None
+            shutil.rmtree(workspace)
+        
+        with tarfile.open(path, mode="r:xz") as tar:
+            tar.extractall(path=Path.cwd())
+        
+        # Load metadata
+        metadata_path = workspace / "metadata.json"
+        with open(metadata_path, "r") as f:
+            metadata = json.load(f)
+        
+        return {
+            "workspace": workspace,
+            "metadata": metadata
+        }
+    
+    @staticmethod
+    def load_native_model(workspace: Path, ml_backend: str):
+        """Load native model from workspace"""
+        if ml_backend in ("keras", "qkeras"):
+            try:
+                tf_keras = importlib.import_module("keras.models")
+            except ModuleNotFoundError:
+                tf_keras = importlib.import_module("tensorflow.keras.models")
+            return tf_keras.load_model(workspace / "keras_model")
+        elif ml_backend == "xgboost":
+            import xgboost as xgb
+            model = xgb.Booster()
+            model.load_model(str(workspace / "xgb_model.json"))
+            return model
+        else:
+            raise ValueError(f"Unsupported ml_backend: {ml_backend}")
+    
+    @staticmethod
+    def load_qonnx_model(workspace: Path):
+        """Load QONNX model if it exists"""
+        qonnx_path = workspace / "model_qonnx.onnx"
+        if qonnx_path.exists():
+            from qonnx.core.modelwrapper import ModelWrapper
+            model = ModelWrapper(str(qonnx_path))
+            input_name = model.graph.input[0].name
+            return model, input_name
+        return None, None
+
+class TriggerModel:
+    """Main facade class that orchestrates model conversion, compilation, and inference"""
+    
+    def __init__(self, name: str, ml_backend: str, scales: dict, n_outputs:int, compiler: str,
+                 native_model: object, dataset_object: object, compiler_config: dict = None):
+        
+        if ml_backend.lower() not in ("keras", "xgboost"):
+            raise ValueError("Only Keras or XGBoost backends are currently supported.")
+        
+        self.name = name
+        self.ml_backend = ml_backend.lower()
+        self.scales = scales
+        self.n_outputs = n_outputs
+        self.compiler = compiler.lower()
+        self.native_model = native_model
+        self.dataset_object = dataset_object
+        self.compiler_conifg = compiler_config
+        
+        self.workspace_manager = WorkspaceManager()
+        self.converter = ConverterFactory.create_converter(ml_backend, compiler)
+        self.compiler_strategy = CompilerFactory.create_compiler(ml_backend, compiler)
+        
+        self.firmware_model = None
+        self.model_qonnx = None
+        self.input_name = None
+        
+        self.workspace_manager.setup_workspace(name, self.ml_backend, self.compiler)
+    
+    @property
+    def workspace(self) -> Path:
+        """Get workspace path"""
+        return self.workspace_manager.workspace
+    
+    @property
+    def artifacts(self) -> Dict[str, Any]:
+        """Get artifacts dictionary"""
+        return self.workspace_manager.artifacts
+    
+    @property
+    def metadata(self) -> Dict[str, Any]:
+        """Get metadata dictionary"""
+        return self.workspace_manager.metadata
+    
+    def __call__(self, **compiler_kwargs):
+        """Execute the full model conversion and compilation pipeline"""
+        self.parse_dataset_object()
+        
+        # Save native model
+        self.workspace_manager.save_native_model(self.native_model, self.ml_backend)
+        
+        # Convert model if needed
+        conversion_result = self.converter.convert(
+            self.native_model, 
+            self.workspace_manager.workspace
+        )
+        
+        if conversion_result is not None:
+            qonnx_path, self.model_qonnx = conversion_result
+            self.input_name = self.model_qonnx.graph.input[0].name
+            self.workspace_manager.add_artifact("qonnx", qonnx_path)
+            self.workspace_manager.add_version({"qonnx": str(qonnx_path)})
+        
+        # Compile model
+        self.firmware_model = self.compiler_strategy.compile(
+            self.native_model,
+            self.workspace_manager.workspace,
+            self.compiler_conifg, 
+            **compiler_kwargs
+        )
+        
+        self.workspace_manager.add_artifact("firmware", self.workspace_manager.workspace / "firmware")
+
+        self.build_emulator(self.scales['shifts'], self.scales['offsets'], self.n_outputs)
+        
+        self.workspace_manager.add_artifact("firmware", self.workspace_manager.workspace / "firmware")
+        self.workspace_manager.save_metadata()
+    
+    @staticmethod
+    def parse_dataset_object():
+        """Parse dataset object (placeholder)"""
+        pass
+
+    @staticmethod
+    def _render_template(template_path: Path, out_path: Path, context: dict):
+        """Simple template substitution"""
+        with open(template_path) as f:
+            template = f.read()
+        for k, v in context.items():
+            template = template.replace("{{" + k + "}}", str(v))
+        with open(out_path, "w") as f:
+            f.write(template)
+    
+    def software_predict(self, input_data: np.ndarray) -> np.ndarray:
+        """Make predictions using software model"""
+        predictor = SoftwarePredictor(self.native_model, self.ml_backend)
+        return predictor.predict(input_data)
+    
+    def qonnx_predict(self, input_data: np.ndarray) -> np.ndarray:
+        """Make predictions using QONNX model"""
+        if self.model_qonnx is None:
+            raise RuntimeError("QONNX model not available")
+        predictor = QONNXPredictor(self.model_qonnx, self.input_name)
+        return predictor.predict(input_data)
+    
+    def firmware_predict(self, input_data: np.ndarray) -> np.ndarray:
+        """Make predictions using firmware model"""
+        predictor = FirmwarePredictor(self.firmware_model)
+        return predictor.predict(input_data)
+    
+    def build_emulator(self, ad_shift: list, ad_offsets: list, n_outputs: int):
+        """
+        Create an emulator directory for this model.
+        Copies HLS sources and generates emulator scaffolding.
+        """
+        emulator_dir = self.workspace / "emulator"
+        emulator_dir.mkdir(exist_ok=True)
+
+        model_dir = emulator_dir / self.name 
+        model_dir.mkdir(exist_ok=True)
+        
+        firmware_dir = self.workspace / "firmware" / "firmware"
+        
+        shutil.copytree(firmware_dir, f"{model_dir}/NN", dirs_exist_ok=True)
+        
+        # Access scales template from installed package
+        with pkg_resources.path(triggerflow.templates, "scales.h") as scales_template_path:
+            scales_out_path = model_dir / "scales.h"
+            context = {
+                "MODEL_NAME": self.name,
+                "N_INPUTS": len(ad_shift),
+                "N_OUTPUTS": n_outputs,
+                "AD_SHIFT": ", ".join(map(str, ad_shift)),
+                "AD_OFFSETS": ", ".join(map(str, ad_offsets)),
+            }
+            self._render_template(scales_template_path, scales_out_path, context)
+
+        with pkg_resources.path(triggerflow.templates, "model_template.cpp") as emulator_template_path:
+            emulator_out_path = model_dir / "emulator.cpp"
+            self._render_template(emulator_template_path, emulator_out_path, context)
+        
+        with pkg_resources.path(triggerflow.templates, "makefile_version") as makefile_template_path:
+            makefile_out_path = model_dir / "Makefile"
+            self._render_template(makefile_template_path, makefile_out_path, {"MODEL_NAME": self.name})
+
+        with pkg_resources.path(triggerflow.templates, "makefile") as makefile_template_path:
+            makefile_out_path = emulator_dir / "Makefile"
+            self._render_template(makefile_template_path, makefile_out_path, {"MODEL_NAME": self.name})
+        
+    
+    def save(self, path: str):
+        """Save the complete model to an archive"""
+        ModelSerializer.save(self.workspace_manager.workspace, path)
+    
+    @classmethod
+    def load(cls, path: str) -> 'TriggerModel':
+        """Load a model from an archive"""
+        load_result = ModelSerializer.load(path)
+        if load_result is None:
+            return None
+        
+        workspace = load_result["workspace"]
+        metadata = load_result["metadata"]
+        
+        obj = cls.__new__(cls)
+        obj.workspace_manager = WorkspaceManager()
+        obj.workspace_manager.workspace = workspace
+        obj.workspace_manager.metadata = metadata
+        obj.workspace_manager.artifacts = {"firmware": workspace / "firmware"}
+        
+        obj.name = metadata.get("name", "")
+        obj.ml_backend = metadata.get("ml_backend")
+        obj.compiler = metadata.get("compiler")
+        
+        obj.native_model = ModelSerializer.load_native_model(workspace, obj.ml_backend)
+        
+        obj.model_qonnx, obj.input_name = ModelSerializer.load_qonnx_model(workspace)
+        
+        if obj.compiler.lower() in ("hls4ml", "conifer"):
+            obj.compiler_strategy = CompilerFactory.create_compiler(obj.ml_backend, obj.compiler)
+            obj.firmware_model = obj.compiler_strategy.load_compiled_model(workspace)
+        else:
+            obj.firmware_model = None
+            obj.compiler_strategy = None
+        
+        obj.converter = ConverterFactory.create_converter(obj.ml_backend, obj.compiler)
+        obj.dataset_object = None 
+        
+        return obj

triggerflow-0.1.4/src/triggerflow/mlflow_wrapper.py

@@ -0,0 +1,100 @@
+# trigger_mlflow.py
+import mlflow
+import mlflow.pyfunc
+import tempfile
+from pathlib import Path
+from typing import Dict, Any
+from mlflow.tracking import MlflowClient
+from core import TriggerModel
+
+
+class MLflowWrapper(mlflow.pyfunc.PythonModel):
+    """PyFunc wrapper for TriggerModel; backend can be set at runtime."""
+    def load_context(self, context):
+        archive_path = Path(context.artifacts["trigger_model"])
+        self.model = TriggerModel.load(archive_path)
+        self.backend = "software" 
+
+    def predict(self, context, model_input):
+        if self.backend == "software":
+            return self.model.software_predict(model_input)
+        elif self.backend == "qonnx":
+            if self.model.model_qonnx is None:
+                raise RuntimeError("QONNX model not available.")
+            return self.model.qonnx_predict(model_input)
+        elif self.backend == "firmware":
+            if self.model.firmware_model is None:
+                raise RuntimeError("Firmware model not available.")
+            return self.model.firmware_predict(model_input)
+        else:
+            raise ValueError(f"Unsupported backend: {self.backend}")
+
+    def get_model_info(self):
+        if hasattr(self.model, "get_model_info"):
+            return self.model.get_model_info()
+        return {"error": "Model info not available"}
+
+
+def _get_pip_requirements(trigger_model: TriggerModel) -> list:
+    requirements = ["numpy"]
+    if trigger_model.ml_backend == "keras":
+        requirements.extend(["tensorflow", "keras"])
+    elif trigger_model.ml_backend == "xgboost":
+        requirements.append("xgboost")
+    if trigger_model.compiler == "hls4ml":
+        requirements.append("hls4ml")
+    elif trigger_model.compiler == "conifer":
+        requirements.append("conifer")
+    if hasattr(trigger_model, "model_qonnx") and trigger_model.model_qonnx is not None:
+        requirements.append("qonnx")
+    return requirements
+
+
+def log_model(trigger_model: TriggerModel, registered_model_name: str, artifact_path: str = "TriggerModel"):
+    """Log a TriggerModel as a PyFunc model and register it in the Model Registry."""
+    if not registered_model_name:
+        raise ValueError("registered_model_name must be provided and non-empty")
+
+    if mlflow.active_run() is None:
+        raise RuntimeError("No active MLflow run. Start a run before logging.")
+
+    run = mlflow.active_run()
+    with tempfile.TemporaryDirectory() as tmpdir:
+        archive_path = Path(tmpdir) / "triggermodel.tar.xz"
+        trigger_model.save(archive_path)
+
+        mlflow.pyfunc.log_model(
+            artifact_path=artifact_path,
+            python_model=MLflowWrapper(),
+            artifacts={"trigger_model": str(archive_path)},
+            pip_requirements=_get_pip_requirements(trigger_model)
+        )
+
+        # register model (always required)
+        client = MlflowClient()
+        model_uri = f"runs:/{run.info.run_id}/{artifact_path}"
+        try:
+            client.get_registered_model(registered_model_name)
+        except mlflow.exceptions.RestException:
+            client.create_registered_model(registered_model_name)
+        client.create_model_version(
+            name=registered_model_name,
+            source=model_uri,
+            run_id=run.info.run_id
+        )
+
+def load_model(model_uri: str) -> mlflow.pyfunc.PyFuncModel:
+    return mlflow.pyfunc.load_model(model_uri)
+
+
+def load_full_model(model_uri: str) -> TriggerModel:
+    local_path = mlflow.artifacts.download_artifacts(model_uri)
+    archive_path = Path(local_path) / "trigger_model" / "triggermodel.tar.xz"
+    return TriggerModel.load(archive_path)
+
+
+def get_model_info(model_uri: str) -> Dict[str, Any]:
+    model = mlflow.pyfunc.load_model(model_uri)
+    if hasattr(model._model_impl, "get_model_info"):
+        return model._model_impl.get_model_info()
+    return {"error": "Model info not available"}

triggerflow-0.1.4/src/triggerflow/templates/makefile

@@ -0,0 +1,28 @@
+CPP_STANDARD := c++17
+CXXFLAGS := -O3 -fPIC -std=$(CPP_STANDARD)
+PREFIX := .
+EMULATOR_EXTRAS := ../../hls4mlEmulatorExtras
+AP_TYPES := $(EMULATOR_EXTRAS)/include/ap_types
+HLS_ROOT := ../../hls
+HLS4ML_INCLUDE := $(EMULATOR_EXTRAS)/include/hls4ml
+INCLUDES := -I$(HLS4ML_INCLUDE) -I$(AP_TYPES) -I$(HLS_ROOT)/include
+LD_FLAGS := -L$(EMULATOR_EXTRAS)/lib64 -lemulator_interface
+ALL_VERSIONS := {{MODEL_NAME}}/{{MODEL_NAME}}.so
+
+.DEFAULT_GOAL := all
+.PHONY: all clean install
+
+all: $(ALL_VERSIONS)
+	@cp $(ALL_VERSIONS) ./
+	@echo All OK
+
+install: all
+	@rm -rf $(PREFIX)/lib64
+	@mkdir -p $(PREFIX)/lib64
+	cp {{MODEL_NAME}}/{{MODEL_NAME}}.so $(PREFIX)/lib64
+
+%.so:
+	$(MAKE) -C $(@D) INCLUDES="$(INCLUDES)" LD_FLAGS="$(LD_FLAGS)" CXXFLAGS="$(CXXFLAGS)"
+
+clean:
+	rm -rf {{MODEL_NAME}}/{{MODEL_NAME}}.so $(ALL_VERSIONS)

triggerflow-0.1.4/src/triggerflow/templates/makefile_version

@@ -0,0 +1,15 @@
+.PHONY: clean
+
+MODEL_NAME = {{MODEL_NAME}}
+
+$(MODEL_NAME).so: $(MODEL_NAME)_project.o $(MODEL_NAME).o
+	$(CXX) $(CXXFLAGS) $(LD_FLAGS) -shared $^ -o $@
+
+%.o: NN/%.cpp
+	$(CXX) $(CXXFLAGS) $(INCLUDES) -c $< -o $@
+
+%.o: %.cpp
+	$(CXX) $(CXXFLAGS) $(INCLUDES) -c $< -o $@
+
+clean:
+	rm -f $(MODEL_NAME)_project.o $(MODEL_NAME).o $(MODEL_NAME).so

triggerflow-0.1.4/src/triggerflow/templates/model_template.cpp

@@ -0,0 +1,59 @@
+#include "NN/{{MODEL_NAME}}.h"
+#include "emulator.h"
+#include "NN/nnet_utils/nnet_common.h"
+#include <any>
+#include <array>
+#include <utility>
+#include "ap_fixed.h"
+#include "ap_int.h"
+#include "scales.h"
+
+using namespace hls4ml_{{MODEL_NAME}};
+
+class {{MODEL_NAME}}_emulator : public hls4mlEmulator::Model {
+
+private:
+    unscaled_t _unscaled_input[N_INPUT_1_1];
+    input_t _scaled_input[N_INPUT_1_1];
+    result_t _result[{{N_OUTPUTS}}];
+
+    virtual void _scaleNNInputs(unscaled_t unscaled[N_INPUT_1_1], input_t scaled[N_INPUT_1_1])
+    {
+        for (int i = 0; i < N_INPUT_1_1; i++)
+        {
+            unscaled_t tmp0 = unscaled[i] - hls4ml_{{MODEL_NAME}}::ad_offsets[i];
+            input_t tmp1 = tmp0 >> hls4ml_{{MODEL_NAME}}::ad_shift[i];
+            scaled[i] = tmp1;
+        }
+    }
+
+public: 
+    virtual void prepare_input(std::any input) {
+        unscaled_t *unscaled_input_p = std::any_cast<unscaled_t*>(input);
+        
+        for (int i = 0; i < N_INPUT_1_1; i++) {
+            _unscaled_input[i] = std::any_cast<unscaled_t>(unscaled_input_p[i]);
+        }
+
+        _scaleNNInputs(_unscaled_input, _scaled_input);
+    }
+
+    virtual void predict() {
+        {{MODEL_NAME}}(_scaled_input, _result);
+    }
+  
+    virtual void read_result(std::any result) {
+        result_t *result_p = std::any_cast<result_t*>(result);
+        for (int i = 0; i < {{N_OUTPUTS}}; i++) {
+            result_p[i] = _result[i];
+        }
+    }
+};
+
+extern "C" hls4mlEmulator::Model* create_model() {
+    return new {{MODEL_NAME}}_emulator;
+}
+
+extern "C" void destroy_model(hls4mlEmulator::Model* m) {
+    delete m;
+}

triggerflow-0.1.4/src/triggerflow/templates/scales.h

@@ -0,0 +1,20 @@
+#ifndef __ADT_SCALES_H
+#define __ADT_SCALES_H
+
+#include "NN/{{MODEL_NAME}}.h"
+
+namespace hls4ml_{{MODEL_NAME}} {
+
+typedef ap_fixed<5,5> ad_shift_t;
+typedef ap_fixed<10,10> ad_offset_t;
+
+const ad_shift_t ad_shift[{{N_INPUTS}}] = {
+    {{AD_SHIFT}}
+};
+
+const ad_offset_t ad_offsets[{{N_INPUTS}}] = {
+    {{AD_OFFSETS}}
+};
+
+} // namespace hls4ml_{{MODEL_NAME}}
+#endif

triggerflow-0.1.4/src/triggerflow.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: triggerflow
+Version: 0.1.4
+Summary: Utilities for ML models targeting hardware triggers
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mlflow>=2.0
+
+# Machine Learning for Hardware Triggers
+
+`triggerflow` provides a set of utilities for Machine Learning models targeting FPGA deployment. 
+The `TriggerModel` class consolidates several Machine Learning frontends and compiler backends to construct a "trigger model". MLflow utilities are for logging, versioning, and loading of trigger models.
+
+## Installation
+
+```bash
+pip install triggerflow
+```
+
+## Usage
+
+```python
+
+from triggerflow.core import TriggerModel 
+
+trigger_model = TriggerModel(name="my-trigger-model", ml_backend="Keras", compiler="hls4ml", model, compiler_config or None)
+trigger_model() # call the constructor
+
+# then:
+output_software = trigger_model.software_predict(input_data)
+output_firmware = trigger_model.firmware_predict(input_data)
+output_qonnx = trigger_model.qonnx_predict(input_data)
+
+# save and load trigger models:
+trigger_model.save("trigger_model.tar.xz")
+
+# in a separate session:
+from trigger_model.core import TriggerModel 
+trigger_model = TriggerModel.load("trigger_model.tar.xz")
+```
+
+## Logging with MLflow
+
+```python
+# logging with MLFlow:
+import mlflow
+from trigger_model.mlflow_wrapper import log_model
+
+mlflow.set_tracking_uri("https://ngt.cern.ch/models")
+experiment_id = mlflow.create_experiment("example-experiment")
+
+with mlflow.start_run(run_name="trial-v1", experiment_id=experiment_id):
+    log_model(trigger_model, registered_model_name="TriggerModel")
+```
+
+### Note: This package doesn't install dependencies so it won't disrupt specific training environments or custom compilers. For a reference environment, see `environment.yml`.
+
+

triggerflow-0.1.4/src/triggerflow.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+src/triggerflow/__init__.py
+src/triggerflow/core.py
+src/triggerflow/mlflow_wrapper.py
+src/triggerflow.egg-info/PKG-INFO
+src/triggerflow.egg-info/SOURCES.txt
+src/triggerflow.egg-info/dependency_links.txt
+src/triggerflow.egg-info/requires.txt
+src/triggerflow.egg-info/top_level.txt
+src/triggerflow/templates/makefile
+src/triggerflow/templates/makefile_version
+src/triggerflow/templates/model_template.cpp
+src/triggerflow/templates/scales.h
+tests/test.py

triggerflow-0.1.4/src/triggerflow.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

triggerflow-0.1.4/src/triggerflow.egg-info/requires.txt

@@ -0,0 +1 @@
+mlflow>=2.0

triggerflow-0.1.4/src/triggerflow.egg-info/top_level.txt

@@ -0,0 +1 @@
+triggerflow

triggerflow-0.1.4/tests/test.py

@@ -0,0 +1,62 @@
+import pytest
+from triggerflow.core import TriggerModel
+import numpy as np
+from qkeras.qlayers import QDense, QActivation
+from qkeras.quantizers import quantized_bits
+from keras.models import Sequential
+
+from qkeras.qlayers import QDense, QActivation
+from qkeras.quantizers import quantized_bits
+from keras.models import Model
+from keras.layers import Input
+from keras.layers import *
+
+def make_dummy_model():
+
+
+
+    inputs = Input(shape=(57,))
+
+    x = QDense(
+        units=64,
+        name='fc1',
+        kernel_quantizer=quantized_bits(bits=6, alpha=1),
+        bias_quantizer=quantized_bits(bits=6, alpha=1)
+    )(inputs)
+
+    x = QActivation("quantized_relu(3)")(x)
+
+    outputs = QDense(
+        units=1,
+        name='last',
+        kernel_quantizer=quantized_bits(bits=6, alpha=1),
+        bias_quantizer=quantized_bits(bits=6, alpha=1)
+    )(x)
+
+    model = Model(inputs=inputs, outputs=outputs)
+    return model
+
+
+
+def test_predict():
+    name = "Dummy"
+    dummy_model = make_dummy_model()
+    scales = {'offsets': np.array([18, 0, 72, 7, 0, 73, 4, 0, 73, 4, 0, 72, 3, 0, 72, 6, -0, 286, 3, -2, 285, 3, -2, 282, 3, -2, 286, 29, 0, 72, 22, 0, 72, 18, 0, 72, 14, 0, 72, 11, 0, 72, 10, 0, 72, 10, 0, 73, 9, 0, 73, 9, 0, 72, 8, -2, 72], dtype='int'),
+          'shifts': np.array([3, 0, 6, 2, 5, 6, 0, 5, 6, 0, 5, 6, -1, 5, 6, 2, 7, 8, 0, 7, 8, 0, 7, 8, 0, 7, 8, 4, 6, 6, 3, 6, 6, 3, 6, 6, 3, 6, 6, 3, 6, 6, 3, 6, 6, 3, 6, 6, 3, 6, 6, 3, 6, 6, 2, 6, 6], dtype='int')}
+    trigger_model = TriggerModel(
+        name=name,
+        ml_backend="Keras",
+        scales=scales,
+        n_outputs=int(1),
+        compiler="hls4ml",
+        native_model=dummy_model,
+        dataset_object=None,      
+        compiler_config=None
+    )
+    trigger_model(project_name = name+"_project", namespace = name, write_weights_txt = False)
+    input_data = np.ones((10,57))
+    output = trigger_model.software_predict(input_data)
+    output = trigger_model.firmware_predict(input_data)
+    output = trigger_model.qonnx_predict(input_data)
+    assert output is not None
+