Quantum construction plugin (D-Wave)

This guide describes the D-Wave quantum plugin for JOpt.TourOptimizer: what it does, how to build and develop it, and how to activate it in a request to the TourOptimizer REST server (Spring WebFlux). It is for developers who have access to the plugin and run it with their own TourOptimizer server. The REST part assumes a running server; see TourOptimizer REST server.

Before you start

• Access to the plugin: it is not available to customers by default; contact DNA Evolutions.
• A JDK in the version that the plugin's pom.xml sets.
• Eclipse IDE for Java Developers.
• Apache Maven.
• For the REST part: a running TourOptimizer server, see TourOptimizer REST server.

What it does

The D-Wave quantum plugin is a Java Maven project that adds quantum computing to JOpt.TourOptimizer. It is a construction algorithm plugin: it applies D-Wave quantum computing to a traveling salesman problem (TSP) and plugs into TourOptimizer as a construction backend. Its result is a heuristic starting solution, which the later optimization phases can improve.

The plugin:

• implements the TourOptimizer plugin interface for construction algorithms;
• reads a JSON settings object, serialized into a string, that configures:
  • the QUBO calculation parameters, for example the Lagrange parameter;
  • the endpoint setup, including dummy responses;
  • the D-Wave solver properties: token, solver, reads, time limit, label and more.

When to use it

Use the plugin to build the starting solution of an optimization, especially for TSP-like subproblems.

How to use it

Build the plugin JAR

The build produces a fat jar with its dependencies, for example jopt.cloud.touroptimizer.plugin.quantum-0.0.1-SNAPSHOT-with-dep.jar; the version part follows the <version> in your pom.xml.

Build steps, with a focus on Windows and Eclipse:

1. Clone the project (plugin repository).
2. Open the project in Eclipse: import the cloned Maven project.
3. Set up annotation processing (Immutables):
   • Install m2e-apt from the Eclipse marketplace; it enables annotation processing driven by Maven.
   • Enable the JDT/APT autoconfiguration, globally or per project.
   • Reference: Immutables, annotation processing in the IDE.
4. 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.
5. Change the project version (optional): update <version>0.0.1-SNAPSHOT</version> in pom.xml; the value is a sample.
6. Build the project: in Eclipse with Run As > Maven Build... and the goals clean package, or on the command line with mvn clean package.

The build writes the output into the project's target/ folder; Eclipse can take a while to index the generated classes.

Develop the plugin

Dummy settings creator

DummyQuantumDwaveSettingsCreator creates dummy settings for a D-Wave quantum computer. It generates a QuantumDwaveSettings instance that can be serialized into the jsonSettings string that the plugin needs:

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

Plugin class

QunatumSingleTSPDwaveConstructionPlugin is the plugin implementation. It implements the interface ITourOptimizerConstructionAlgorithmPlugin:

• prepare(optimization, mapper, jsonSettings) prepares the run: it sets up resources, modifies optimization properties, clusters entities and more.
• invoke() runs the quantum optimization (TSP) and returns an OptimizationAlgorithmPluginResult.

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

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

Local debugging with FullstackExample

FullstackExample is a standalone application that simulates the whole workflow without Spring. Use it to develop and debug:

• the QUBO generation;
• the endpoint behaviour;
• the solver configuration;
• the validation of results.

Integrate into the TourOptimizer server

Build the plugin jar with Maven:

mvn clean install

The jar is placed in the plugin project's target/ folder. For the versions:

• 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 with the server and the plugin

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

• the base image dnaevolutions/jopt_touroptimizer:latest;
• the plugin jar, copied into the container or available to it.

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

Activate the plugin in a request

The plugin is configured in the request JSON under extension.pluginSettings.plugins. Its settings go into jsonSetting as a JSON string. A sample extension object; the values are examples:

"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"
}

Sample plugin settings, to be serialized into the jsonSetting string; the values are examples:

{
  "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
  }
}

• jsonSetting must be a valid JSON string; escape it if you embed it by hand.
• Replace the sample values with your own token, endpoint and solver parameters.
• Add the extension object at its place in your full request.

Practical notes

JSON as a string

The plugin settings arrive as a JSON string. Serialize them, for example with an ObjectMapper as in the dummy settings creator, to avoid escaping errors.

Dummy responses

Use endpointSetup.isDummyResponse to validate the wiring without consuming real quantum resources.

Timeouts

Tune extension.timeOut to your solver settings (read, timelimit) and to the compute time you expect.

Related pages

• TourOptimizer REST server: run and configure the TourOptimizer server
• REST clients: the client libraries that build and send optimization requests
• Clustering during construction: the default construction algorithm

Added: 2026-02-27 (JOpt core 7.5.3-j17) | Last updated: 2026-10-19