Documentation Hub

Learn & Explore through Real-World Examples

Welcome to the DNA Evolutions Documentation Hub — the central place to understand the JOpt product family, explore capabilities, and navigate to the right depth of documentation.

This hub focuses on three products:

• JOpt.TourOptimizer — optimization engine for routing, scheduling, and resource planning under real-world constraints.
• JOpt.RouterPlanner — routing and travel-time planning layer to obtain realistic distances, durations, and routing context.
• JOpt.GeoCoder — geocoding and geo-referencing layer to turn business locations into route-ready coordinates/ids.

If you’re looking for setup commands and container details, use the Quickstart - Getting started page and Quickstart - Sandboxes page.

The JOpt platform in one picture

JOpt projects often follow a simple, practical flow:

1. GeoCoder makes locations route-ready
2. RouterPlanner provides realistic travel-time / distance intelligence
3. TourOptimizer produces feasible schedules and optimizes them according to business objectives

How to read this documentation Hub

The hub is structured to support your learning journey:

1) Onboarding

Getting Started

• Introduction: You are here
• Quickstart: How to do a fast onboarding, learn the basic elements of JOpt and perform your first Optimization run.

Learn & Explore

• Feature Overview: The features JOpt.TourOptimizer supports as a sorted list or as atlas.
• Feature Guides: A collection of whitepapers targeting a particular feaure. For example, how to utilize JOpt Sandboxes to integrate JOpt-TourOptimizer in the programming language of your choice.
• Special: A collection of unique features that are speical about the DNA Evolutions platform.
• Basic Examples: A collection of unique features that are speical about the DNA Evolutions platform.

2) Learn by examples

JOpt documentation is example-centric. Each example has its own Markdown page explaining:

• the purpose (why it exists),
• the scenario (what it models),
• what to look for in the output and KPIs.

Examples are grouped by depth:

• Base Examples: Fundamentals and core modeling patterns
• Advanced Examples: Real-world constraints and feature combinations
• Expert Examples: Customization hooks, performance strategies, deep integration patterns

All our examples are hosted on GitHub.

3) Integrate into your product

Integration guidance is organized around your chosen architecture (SDK or REST/OpenAPI) and the product components you adopt (TourOptimizer alone, or the full pipeline including GeoCoder and RouterPlanner). Implementation specifics live in the dedicated integration and sandbox documents. Also see the different options for container deployment like JOpt.TourOptimizer on Kubernetes

Integrated

Integrating the JOpt components into existing solutions is straight forward as it is docker compatible using the famous Swagger REST-API, or directly integrable as native Java dependency accessible via Maven or as direct Jar download. Whatever your programming environment is, REST facilitates software integration in your desired language (including famous ones like C#, Java, JS, Scala, Python, and many more ). Only JOpt.TourOptimizer supports a direct jar integration.

Conceptual introduction to JOpt.TourOptimizer

The sections below explain the kind of problems JOpt is built for and the high-level working principle of the engine. They are written to be understandable without requiring implementation knowledge. Watch our introduction video. Click, to open video.

Problem description - Overview

Allocating a set of tasks or shipments to mobile resources is a standard problem for dispatchers. The dispatchers' challenge is to find the right balance of "who should do what" or "who should deliver which shipment".

Once the allocation of the tasks and shipments (to the resources) are done, the set of tour stops must be ordered, ideally, in the most efficient way. For example, an order in which opening hours (at the tour stops) and all additional constraints are met. These constraints, for example, are working- and travel-time regulations, drivers' skills, and transportation rules, personal preferences of both resources and customers, already negotiated and assured appointment times, and many more.

For meeting all these constraints, although some of them may conflict with others while at the same time, the final result should be the most cost-effective one. Cost in our case in an abstract number uniting the costs from traveling-distances, traveling- and working-times, as well as fuel cost and even CO2 emission. Manually, this dispatching work is time-consuming, and reasonable solutions require experience. For huge problem sets, in fact, it is almost impossible to dispatch jobs and resources manually.

Working principle

State of the art algorithms can help to solve big dispatch problem sets and find a convincing solution in a reasonable time.

In our case, we provide a software package called JOpt, containing performance-optimized algorithms and a modern API for user interaction. JOpt takes the given set of resources, jobs, and shipments as well as all the constraints and will return an optimized solution. The optimized solution can be further processed, which will then be given, for example, to the dispatcher on the HMI of your program suite.

By default, the JOpt-TourOptimizer engine uses a powerful combination of construction-algorithms, a simulated annealing algorithm, and a genetic algorithm to find the optimal solution. The genetic algorithm internally uses, roughly spoken, two different kinds of operators. Random Operators hat perform random mutations/crossings as you would find in nature. Furthermore, it uses intelligent Operators. They evaluate a solution before/after modification and remind on LocalSearch Strategies.

Constructing a heuristic starting solution

When using the default JOpt's optimization scheme, the first step of JOpt is to find a suitable starting solution based on all inputs. JOpt takes all the tasks, shipments, and allocates them to the set of resources using a construction algorithm. One of our construction algorithms, for example, originates from the ideas of the savings algorithm, a widely used heuristic algorithm for solving capacitated vehicle routing problems. During this first step of the optimization, a heuristic solution will be achieved by rearranging all the tour stops and allocating them to the resources until finally, an acceptable starting solution is found based on different aspects, for example, the distance between tour-stops. Constraints are avoided by adding additional penalties.

Furthermore, additional weights (as optional user input) can help to modify the optimizer to balance adequately different KPIs for a given problem set. For example, it could be more important to meet agreed appointment times rather than to have minimum traveling times.

Improving the starting solution

Once a first initial solution has been constructed, it can be further optimized by the second step, the simulating annealing algorithm. This algorithm takes the solution from the construction phase and rearranges the tours, and their tour stops sequences in a way to achieve a state with a lower total cost. This algorithm is motivated by physical annealing processes in metallurgy where atoms and crystals are transferred into structures with the lowest energetic state when cooling down from high temperatures.

From a mathematically perspective, this is a probabilistic process modeled in an exponential function to find energetically lower states representing a better solution. The result from this process is usually quite convincing, and simulating annealing is comparable fast end effective. But sometimes simulating annealing tends to stuck in local minima during the optimization process.

Further enhance the quality of the solution

The more complex a problem space is, the more likely it is to end up in an acceptable but not optimal solution. Therefore, in a third step, we feed this solution into a genetic algorithm. The genetic algorithm is a very flexible process suitable for many different kinds of problems. It is simulating the biological process of evolution, trying to find solutions that fit well to a given environment, where the environment here can be understood as the system of constraints, opening hours, working hours, and locations.

In the JOpt-TourOptimizer, genetic evolution is utilized to improve the prior solution found from simulated annealing. Other than in the annealing process, the genetic algorithms develop many parallel solutions that are inherited with few modifications to the next generation of solutions. An elite-concept ensures that the best solutions are always propagated to the next generation. This broader approach can be more time consuming (depending on the initial settings), and the changes from one generation to the next generation can be small with big jumps from time to time.

However, the strength of the attempt lies in the fact that many paths of optimization are explored in parallel. This attempt reduces the danger of getting stuck to a particular solution. Therefore genetic evolution is typically used as the final step of the optimization engine.

Contact

For further information, please contact us.

Authors

A product by dna-evolutions ©