Introduction to the Documentation Hub

This hub is the documentation of the JOpt product family. It covers the first setup, the modeling basics, one guide per feature, examples by level, and integration and deployment. To get a container running right away, start with Getting started or the sandbox quickstart.

The JOpt product family

This hub covers three products that are designed to work together as an end-to-end pipeline:

Product	Role
JOpt.TourOptimizer	Optimization engine for routing, scheduling, and resource planning under real-world constraints
JOpt.RoutePlanner	Routing and travel-time layer for realistic distances, durations, and route shapes
JOpt.GeoCoder	Geocoding layer to turn business addresses into route-ready coordinates

JOpt projects often follow a simple practical flow: GeoCoder makes locations route-ready → RoutePlanner provides realistic travel-time intelligence → TourOptimizer produces and optimizes feasible schedules.

Where to start

You want to	Start here
Run a TourOptimizer container and a first optimization	Getting started
Code in a browser IDE without a local Java, Maven or IDE setup; the sandboxes run in Docker	Sandbox quickstart
Try the Angular demo client in the browser (StackBlitz)	Angular demo client
Learn the modeling elements: nodes, resources, time windows, working hours	Basic elements
Follow a first optimization step by step	First optimization

How the hub is organized

Getting Started

The quickstart pages, the basic tutorials and the FAQ.

Learn & Explore

Features: the feature list, by topic with a level for each feature, and the feature atlas.
Feature guides: one guide per feature, for example JOpt Sandboxes or Clustering during construction.
Special features: the special features page.
REST: the REST client and REST server pages.
Examples, by level:

The three example levels with sample topics: basic for onboarding, advanced for modeling and production, expert for customization

Level	Focus	Examples
Basic	Fundamentals and core modeling patterns	Basic examples
Advanced	Constraints from practice and combinations of features	Advanced examples
Expert	Custom restrictions and costs, warm starts with your own solution, the algorithm pipeline, early stop on convergence	Expert examples
REST	JSON input for the REST service, built in Java and run locally	REST examples

Every example has its own page, and its source code is on GitHub in Java-TourOptimizer-Examples.

System Integration

The system architecture and the container deployment pages.

Integration options

JOpt components are available via:

Docker / REST API: language-agnostic integration via OpenAPI 3. For JOpt.TourOptimizer (Docker image dnaevolutions/jopt_touroptimizer:latest), the examples include generated clients for Java, Python and C#, and the Angular demo client in TypeScript. See REST server.
Native Java dependency: the Maven artifact jopt:jopt.core.pg with the classifier shaded, from the public DNA Evolutions Maven repository. Only JOpt.TourOptimizer supports this mode. See Getting started.

Three ways to integrate: a self-hosted REST API in a container, a managed SaaS API, and the Java library as a dependency

How JOpt.TourOptimizer works

This part explains the problem JOpt.TourOptimizer solves and how its algorithms work together. An introduction video on YouTube covers the same topic.

The problem

A dispatcher assigns tasks or shipments to mobile resources: who visits which customer, in which order and within which time windows. Working-time rules, driver skills, transport rules, customer preferences and agreed appointment times apply at the same time, and some of them conflict. For a small problem a skilled dispatcher can plan by hand. For a large or complex one, planning without an algorithm is practically impossible.

What cost means

JOpt.TourOptimizer looks for the plan with the lowest cost. The cost is made of:

the resource costs set with setCost: a fixed cost, a cost per distance and a cost per time (see Resources, cost model);
penalties for violated constraints, weighted with JOptWeight properties such as JOptWeight.WorkingTime;
optionally CO2 emissions, weighted with JOptWeight.CO2Emission (see CO2 emission).

Three algorithms in sequence

JOpt.TourOptimizer runs three algorithms one after the other. Each starts from the result of the one before. The example algorithm selection shows how to choose the construction algorithm and the phases.

Construction

A deterministic construction algorithm builds a feasible or near-feasible starting solution. One of JOpt's construction algorithms is inspired by the savings algorithm, a common approach to the capacitated vehicle routing problem. The guide Clustering during construction describes the default construction algorithm.

Simulated annealing

Simulated annealing changes the routes and the order of stops to lower the cost. It accepts some worse solutions on the way, with a probability controlled by a starting temperature and a cooling rate, so that it can leave a local minimum (JOpt.Algorithm.PreOptimization.SA.StartingTemperature, JOpt.Algorithm.PreOptimization.SA.CoolingRate, JOpt.Algorithm.PreOptimization.SA.NumIterations). On complex problems it can still settle in a local minimum.

Genetic evolution

The genetic algorithm continues from the simulated annealing result with a population of solutions (JOpt.JOptPopulationSize) over a number of generations (JOptExitCondition.JOptGenerationCount). It explores many variants in parallel and carries the best solutions into each next generation. Random operators add variation; guided operators steer changes toward a lower cost, similar to local search. In the default flow it is the last phase.

FAQ
License guide: the free and the full licenses and their element limits
Optimization properties: the property keys by category, with their defaults
Contact: licenses and the JOpt products

Added: 2026-01-03 (JOpt core 7.5.2-j17) | Last updated: 2026-10-19

Getting started

A first JOpt.TourOptimizer run, with the Java examples in-process or with a REST client against the TourOptimizer container