modrec-workflow/README.md

# Modulation Recognition Demo

RIA Hub Workflows is an automation platform integrated into RIA Hub. This project provides an example machine learning
workflow for signal modulation classification, offering a practical introduction to RIA Hub Workflows


## 📡 The machine learning development workflow

The development of intelligent radio solutions involves multiple steps:

1. First, we need to prepare a machine learning-ready dataset. This involves signal synthesis or capture, followed by 
dataset curation to extract and qualify examples. Finally, we need to perform any required data preprocessing—such as
augmentation—and split the dataset into training and test sets.


2. Secondly, we need to design and train a model. This is typically an iterative process, often accelerated using
techniques such as Neural Architecture Search (NAS) and hyperparameter optimization (HPO), which help automate the
discovery of an effective model structure and optimal hyperparameter settings.


3. Once a machine learning model has been trained and validated, the next step is to build an inference application. 
This step transforms the model from a research artifact into a practical tool capable of making predictions in 
real-world conditions. Building an inference application typically involves several steps including model 
optimization, packaging and integration, and monitoring and logging.

This is a lot of work, and much of it involves tedious software development and repetitive tasks, like setting up and
configuring infrastructure. What's more? There is a shortage of domain expertize in ML and MLOps for radio. That's
where we come in. RIA Hub offers a no-code and low-code solution for automating the end-to-end development of
intelligent radio systems.


## ▶️ RIA Hub Workflows

One of the core principles of RIA Hub is Workflows, which allow users to run jobs in isolated Docker containers.

You can create workflows in one of two ways: 
- Writing YAML and placing it in the special `.riahub/workflows/` directory in your repository.


- Using RIA Hub's built-in tools for Dataset Management, Model Building, and Application Development, which will
automatically generate the YAML workflow file(s) for you.

Workflows can be configured to run automatically on push and pull request events. You can monitor and manage running 
workflows in the 'Workflows' tab in your repository.

Workflows require a _runner_, which retrieves job definitions from RIA Hub, executes them in isolated containers, and
reports the results back to RIA Hub. The next section outlines the convenience and advantage of using Qoherent-hosted
runners. The workflow configuration defines the specifications and settings of the available job containers.

The best part? RIA Hub Workflows are built on [Gitea Actions](https://docs.gitea.com/usage/actions/overview) (similar to [GitHub Actions](https://github.com/features/actions)), providing a
familiar syntax and allowing you to leverage a wide range of third-party Actions.


## ⚙️ Qoherent-hosted runners

Qoherent-hosted runners are workflow runners that Qoherent provides and manages to run your workflows and jobs in
RIA Hub Workflows.

Why use Qoherent-hosted runners?
- Start running workflows right away, without the need to set up your own infrastructure.
- Qoherent maintains runners equipped with access to hardware and tools common for radio ML development, including
SDR testbeds and common embedded targets.

If you want to learn more about the runners we have available, [contact us](https://www.qoherent.ai/contact/) directly. We can also provide
custom runners equipped with specific radio hardware and RAN software upon request.

Want to register your own runner? No problem! Please refer to the RIA Hub documentation for more details.


## 🔍 Modulation Recognition

In radio, the modulation scheme refers to the method used to encode information onto a carrier signal. Common schemes
such as BPSK, QPSK, and QAM vary the amplitude, phase, or frequency of the signal in structured ways to represent
digital data. These schemes are fundamental to nearly all wireless communication systems, enabling efficient and
reliable transmission over different channels and under various noise conditions.

Machine learning-based modulation classification helps identify which modulation scheme is being used, especially
in scenarios where prior knowledge of the signal format is unavailable or unreliable. Traditional methods often rely
on expert-designed features and rule-based algorithms, which can struggle in real-world environments with multipath,
interference, or hardware impairments. In contrast, ML-based approaches can learn complex patterns directly from 
raw signal data, offering higher robustness and adaptability. This is particularly valuable in applications like
cognitive radio, spectrum monitoring, electronic warfare, and autonomous communication systems, where accurate and
fast modulation recognition is critical.


## 🚀 Getting started

1. Fork the project repo, using the button in the upper right hand corner.


2. Enable Workflows (*Settings → Advanced Settings → Enable Repository Actions*).
_TODO: Remove this point once default units have been updated to include actions in forks_


3. Check for available runners. The runner management tab can found at the top of the 'Workflows' tab in your
repository. If no runners are available, you'll need to register one before proceeding.


4. Configure Git API credentials, if not suitable credentials are already set. This is required for accessing Utils
in the job container. This requires three steps:

   - Create a personal access token with the following permissions: `read:packages` (*User Settings → Applications → Manage Access Tokens*).

   - Create a Workflow Variable `RIAHUB_USER` with your RIA Hub username (*Repo Settings → Actions → Variables Management*)

   - Create a Workflow Secret `RIAHUB_TOKEN` with the token created above (*Repo Settings → Actions → Secrets Management*)

   _TODO: Remove this point once the Utils wheel file has been added to this project._


5. Clone down the project. For example:
```commandline
git clone https://git.riahub.ai/user/modrec-workflow.git
cd modrec-workflow
```

6. Set the workflow runner in `.riahub/workflows/workflow.yaml`. The runner is set on line 13: 
```yaml
runs-on: ubuntu-latest-2080
```
**Note:** We recommend running this demo on a GPU-enabled runner. If a GPU runner is not available, you can still run 
the workflow, but we suggest reducing the number of training epochs to keep runtime reasonable.


7. (Optional) Configure the workflow. All parameters—including file paths, model architecture, and training 
settings—are set in `conf/app.yaml`. Want to jump right in? No problem, the default configuration is suitable.


8. Push changes. This will automatically trigger the workflow. You can monitor workflow progress under the 'Workflows'
tab in the repository.


9. Inspect the workflow output. You can expand and collapse individual steps to view terminal output. A check
mark indicates that the step completed successfully.


10. Inspect the workflow artifacts. Additional information on workflow artifacts can be found in the next section.


## Workflow artifacts

This workflow generates several artifacts, including:

- `recordings`: Folder of synthetic signal recordings.


- `dataset`: The training and validation datasets: `train.h5` and `val.h5`, respectively.


- `checkpoints`: Saved model checkpoints. Each checkpoint contains the model’s learned weights at various
stages of training.


- `onnx-file`: The trained model as an [ONNX](https://onnx.ai/) graph.


- `ort-file`: Model in `.ORT` format, recommended for edge deployments. (`.ORT` files are optimized and serialized
by [ONNX Runtime](https://onnxruntime.ai/) for more efficient loading and execution.)


- `profile-data`: Model execution traces, in JSON format. See the section below for instructions on how to inspect the
trace using Perfetto.


## 📊 Inspecting the model trace using Perfetto

[Perfetto](https://ui.perfetto.dev/) is an open-source trace visualization tool developed by Google. It provides a powerful web-based
interface for inspecting model execution traces. Perfetto is especially useful for identifying bottlenecks.

To inspect model trace, navigate to Perfetto. Select *Navigation → Open trace file*, and choose the JSON trace file 
includes in the `profile-data` artifact.


## 🤝 Contribution

We welcome contributions from the community! Whether it's an enhancement, bug fix, or new tutorial, your 
input is valuable. To get started, please [contact us](https://www.qoherent.ai/contact/) directly, we're looking forward to collaborating with
you. 🚀

If you encounter any issues or to report a security vulnerability, please submit a [bug report](https://git.riahub.ai/qoherent/modrec-workflow/issues).

Qoherent is dedicated to fostering a friendly, safe, and inclusive environment for everyone. For more information on
our commitment to diversity, please refer to our [Diversity Statement](https://github.com/qoherent/.github/blob/main/docs/DIVERSITY_STATEMENT.md). 

We kindly insist that all contributors review and adhere to our [Code of Conduct](https://github.com/qoherent/.github/blob/main/docs/CODE_OF_CONDUCT.md) and that all code contributors 
review our [Coding Guidelines](https://github.com/qoherent/.github/blob/main/docs/CODING.md).


## 🖊️ Authorship

This demonstration was developed by [Liyu Xiao](https://www.linkedin.com/in/liyu-xiao-593176206/) during his summer co-op term at Qoherent.

If you like this project, don’t forget to give it a star! ⭐


## 📄 License

This example is **free and open-source**, released under [AGPLv3](https://www.gnu.org/licenses/agpl-3.0.en.html).

Alternative licensing options are available. Alternative licensing options are available. Please [contact us](https://www.qoherent.ai/contact/)
for further details.