✨ Enabling Multi-Core Architectures

[ystade]

Description

This PR adds three properties and parameters to the interface to enable the following features of a multi-core architecture:

• A (top-level) device combines several child devices (cores, processing units, ...). In QDMI these are modelled as child devices. The top-level device can be queried for its child devices through the newly added QDMI_DEVICE_PROPERTY_CHILDDEVICES. The client can retrieve all relevant information about the child devices via directly querying the respective properties of the child devices, such as its status, its fidelity data, ... To facilitate correct handling of the child device handle in the QDMI driver, a new session parameter, QDMI_DEVICE_SESSION_PARAMETER_CHILDDEVICE was added.
• The top-level devices manages and synchronizes the job execution across all child devices. In this case, the jobs can still be created for each child device but these can only be submitted via a batch job that combines all the jobs for the child devices into a single batch via the top-level device. For this, the new program format QDMI_PROGRAM_FORMAT_BATCHJOB was added.

Fixes #227, #141

Usage Example

Let's consider the following example that from the client's perspective

1. initializes a client session
2. retrieves an available device
3. retireves all child devices from that device
4. creates a batch job

Note: The following exampe might not be syntactically correct.

sequenceDiagram
    participant Client
    participant Driver
    participant Device
    note right of Client: Retrieve device and child devices
    Client->>Driver: QDMI_session_alloc(&session)
    Client->>Driver: QDMI_session_init(session)
    Client->>Driver: QDMI_session_query_session_property(session, QDMI_SESSION_PROPERTY_DEVICES, ..., devices.data(), nullptr)
    Client->>Client: device = devices.front()
    Client->>Driver: QDMI_device_query_device_property(device, QDMI_DEVICE_PROPERTY_CHILDDEVICES, ..., clientChildDevices, nullptr)
    Driver->>Device: QDMI_device_session_query_device_property(device_session, QDMI_DEVICE_PROPERTY_CHILDDEVICES, ..., childDevices, nullptr)
    loop for (childDevice : childDevices)
        Driver->>Device: QDMI_device_session_alloc(&deviceSession)
        Driver->>Device: QDMI_device_session_set_parameter(deviceSession, QDMI_DEVICE_SESSION_PARAMETER_CHILDDEVICE, ..., childDevice)
        Driver->>Device: QDMI_device_session_init(deviceSession)
        Driver->>Driver: wrap the initialized device session into a QDMI_Device in the same way as for the device itself
    end
    Driver-->>Client: wrappedChildDevices
    note right of Client: Create and submit batch job
    loop for (childDevice: clientChildDevices)
        Client->>Driver: QDMI_device_create_job(childDevice, &clientChildJob)
        Driver->>Device: QDMI_device_session_create_device_job(childDevice->deviceSession, &childJob)
        Driver-->>Client: wrapped child job
    end
    Client->>Driver: QDMI_device_create_job(device, &clientJob)
    Driver->>Device: QDMI_device_session_create_device_job(device->deviceSession, &job)
    Driver-->>Client: wrapped (batch) job
    Client->>Driver: QDMI_job_set_parameter(clientJob, QDMI_JOB_PARAMETER_PROGRAMFORMAT, ..., QDMI_PROGRAM_FROMAT_BATCHJOB)
    Client->>Driver: QDMI_job_set_parameter(clientJob, QDMI_JOB_PARAMETER_PROGRAM, ..., &clientChildJobs)
    Client->>Driver: QDMI_job_submit(clientJob)
    Driver->>Device: QDMI_device_job_submit(clientJob->deviceJob)

Loading

Checklist:

• The pull request only contains commits that are focused and relevant to this change.
• I have added appropriate tests that cover the new/changed functionality.
• I have updated the documentation to reflect these changes.
• I have added entries to the changelog for any noteworthy additions, changes, fixes, or
  removals.
• I have added migration instructions to the upgrade guide (if needed).
• The changes follow the project's style guidelines and introduce no new warnings.
• The changes are fully tested and pass the CI checks.
• I have reviewed my own code changes.

[ystade]

This is also related to #215

[github-actions]

PR Preview Action v1.6.2
🚀 View preview at https://Munich-Quantum-Software-Stack.github.io/QDMI/pr-preview/pr-230/
Built to branch gh-pages at 2025-10-15 13:44 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[ystade]

I moved the discussion from #227 to this PR to be able to combine it with actual additions to the code. Please, have a look and give feedback. Also feel free to ask any questions.

@burgholzer @mnfarooqi @echavarria-lrz @AdVetter

[ystade]

@echavarria-lrz please, tag further perople in case I forgot someone.

[echavarria-mqv]

@echavarria-lrz please, tag further perople in case I forgot someone.

@jetridl @denialhaag

[mnfarooqi]

Thank you @ystade for working on this and suggesting a solution.

It took me a while to understand how things could work without an example implementation, but I think I get it now. The proposal seems reasonable to me. However, we would need to expand the specification documentation for clarity.

The top-level devices manages and synchronizes the job execution across all child devices. In this case, the jobs can still be created for each child device but these can only be submitted via a batch job that combines all the jobs for the child devices into a single batch via the top-level device. For this, the new program format QDMI_PROGRAM_FORMAT_BATCHJOB was added.

I cannot see this specified in the PR. However, there is no need for the specifications to entangle batch jobs and child devices. I am not sure why a job created on a child device cannot simply be submitted to that device, without the need for the parent device to submit it via a batch job.

[burgholzer]

I am moving this to the 1.3.0 milestone for now as there still seems to be ongoing discussions that need to be resolved and the changes on main have been pretty stable for a while.

[ystade]

The top-level devices manages and synchronizes the job execution across all child devices. In this case, the jobs can still be created for each child device but these can only be submitted via a batch job that combines all the jobs for the child devices into a single batch via the top-level device. For this, the new program format QDMI_PROGRAM_FORMAT_BATCHJOB was added.

I cannot see this specified in the PR. However, there is no need for the specifications to entangle batch jobs and child devices. I am not sure why a job created on a child device cannot simply be submitted to that device, without the need for the parent device to submit it via a batch job.

@mnfarooqi To come back to your point, yes, that is indeed not specified in the PR, as I also do see other possibilities than the described one, a device could handle batch jobs. In the discussed case, you cannot execute individual jobs on the sub-devices; they do need to be pooled in one batch job in the parent device. However, there might be architectures where the former is actually possible in addition to the batch jobs. I see the batch job as a rather flexible way to pool multiple jobs, might even be jobs on the very same device that are submitted as one batch.

P.S.: And yes, I agree, it is hard to grasp w/o an example. However, I think it does not makes sense to have an example for this very specific case in the QDMI repository.