Quantum Construction Plugin (D-Wave)

Last updated: 2026-02-25

This page consolidates the three internal READMEs into a single feature guide for the D-Wave Quantum Plugin used with JOpt.TourOptimizer.

It covers:

how to build the plugin JAR,
how to develop and test it locally, and
how to integrate it into the TourOptimizer Spring/WebFlux REST server.

Terminology note: The quantum plugin is a construction algorithm plugin. It is used to generate a strong heuristic starting solution (especially for TSP-like subproblems), which downstream optimization phases can further improve.

What the plugin does

The D-Wave Quantum Plugin is a Java-based Maven project that integrates quantum computing capabilities into JOpt.TourOptimizer.
It applies D-Wave quantum computing to solve a Traveling Salesman Problem (TSP) and can be plugged into TourOptimizer as a construction backend.

Key points:

Implements the TourOptimizer plugin interface (construction algorithm plugin).
Uses a JSON settings object (serialized into a string) to configure:
- QUBO calculation parameters (e.g., Lagrange),
- endpoint setup (including dummy responses),
- D-Wave solver properties (token, solver, reads, timelimit, label, …).

Build the plugin JAR

Output artifact

The build produces a “fat jar” with dependencies:

jopt.cloud.touroptimizer.plugin.quantum-0.0.1-SNAPSHOT-with-dep.jar

(Version may differ depending on your pom.xml settings.)

Prerequisites (as documented)

Java Development Kit (JDK) 17
https://adoptopenjdk.net/?variant=openjdk17&jvmVariant=hotspot
Eclipse IDE for Java Developers
https://www.eclipse.org/downloads/packages/release/latest
Apache Maven
https://maven.apache.org/download.cgi

Build instructions (Windows/Eclipse focus)

Clone the project (plugin repository).
Open the project in Eclipse: import the cloned Maven project.
Set up annotation processing (Immutables):
- Install m2e-apt from the Eclipse marketplace (enables Maven-driven annotation processing).
- Enable JDT/APT autoconfiguration (globally or per project).
- Reference: https://immutables.github.io/apt.html
Change the JOpt plugin service version (optional):
- Update <jopt-plugin-service.version>0.0.1</jopt-plugin-service.version> in pom.xml to a version available in your configured repositories.
Change the project version (optional):
- Update <version>0.0.1-SNAPSHOT</version> in pom.xml.
Build the project:
- Eclipse: Run As -> Maven Build... → Goals: clean package
- CLI alternative: mvn clean package

Output is written into the project target/ folder. Eclipse may take time to index generated classes.

Develop the plugin (code-level view)

The plugin contains two main classes:

1) `DummyQuantumDwaveSettingsCreator`

Utility for creating dummy settings for a D-Wave quantum computer. It generates a QuantumDwaveSettings instance that can be serialized to the jsonSettings string required by the plugin.

Example usage:

ObjectMapper mapper = new ObjectMapper();
QuantumDwaveSettings settings = DummyQuantumDwaveSettingsCreator.createDummySettings();
String jsonSettings = mapper.writeValueAsString(settings);

2) `QunatumSingleTSPDwaveConstructionPlugin`

Main plugin implementation. It implements the ITourOptimizerConstructionAlgorithmPlugin interface.

prepare(optimization, mapper, jsonSettings)
Prepares execution: sets up resources, modifies optimization properties, clusters entities, etc.
invoke()
Executes the quantum optimization (TSP) and returns an OptimizationAlgorithmPluginResult.

Example usage:

QunatumSingleTSPDwaveConstructionPlugin plugin = new QunatumSingleTSPDwaveConstructionPlugin();
OptimizationAlgorithmPreparationPluginResult prepResult = plugin.prepare(optimization, mapper, jsonSettings);

if (prepResult.isSuccessful()) {
    OptimizationAlgorithmPluginResult result = plugin.invoke();
    // handle the result
}

Local debugging: `FullstackExample`

A standalone application to simulate the full workflow without Spring. Useful for development and debugging of:

QUBO generation,
endpoint behavior,
solver configuration,
result validation.

Integrate into the TourOptimizer Spring server (WebFlux)

Step 1 — Build the plugin jar

Build with Maven:

mvn clean install

The jar is placed in the plugin project target/ folder.

Notes on versioning

Change <jopt-plugin-service.version> in pom.xml to the desired plugin-service version (must exist in repositories).
Change <version> in pom.xml to the desired project version.

Docker image creation (server + plugin)

To run the Spring TourOptimizer application with the quantum plugin, build a Docker image that includes:

the base image dnaevolutions/jopt_touroptimizer:latest
the plugin jar copied/available in the container

Refer to your dedicated Docker README for the exact build steps.

Activate the plugin via REST request payload

The plugin is configured in the request JSON under extension.pluginSettings.plugins.
Settings are provided in jsonSetting as a JSON string.

Example: extension snippet

"extension": {
  "creatorSetting": {
    "creator": "PUBLIC_CREATOR"
  },
  "keySetting": {
    "jsonLicense": "your_license_info_in_json_format"
  },
  "pluginSettings": {
    "plugins": [
      {
        "pluginName": "QunatumSingleTSPDwaveConstructionPlugin",
        "jsonSetting": "your_plugin_specific_settings_in_json_format",
        "isActive": true
      }
    ]
  },
  "timeOut": "PT5M"
}

Example: plugin settings JSON (to be serialized into the jsonSetting string)

{
  "calculationSetup": {
    "lagrange": 30.0,
    "printBestResult": true,
    "printQubo": true
  },
  "endpointSetup": {
    "endpoint": "http://127.0.0.1/qubo",
    "isDummyResponse": false
  },
  "solverProps": {
    "solver": 1,
    "token": "YOUR_DWAVE_TOKEN",
    "read": 1000,
    "solverident": "",
    "label": "myTestOpti_newQ_",
    "timelimit": 10
  }
}

Important:

jsonSetting must be a properly formatted JSON string (ensure escaping if you embed it manually).
Replace example values with your real token/endpoint/solver parameters.
Add the extension snippet into the correct location of your full request payload.