【教程4】OptaPlanner Hello world Java 快速入门

OptaPlanner Hello world Java 快速入门

本指南将引导您完成使用OptaPlanner的约束求解人工智能（AI）创建简单Java应用程序的过程。

1. 您将构建什么

您将构建一个命令行应用程序，该应用程序优化学生和教师的学校课程表：

…
INFO Solving ended: time spent (5000), best score (0hard/9soft), …

	Room A	Room B	Room C
MON 08:30	English	Math
	I. Jones	A. Turing
	9th grade	10th grade
MON 09:30	History	Physics
	I. Jones	M. Curie
	9th grade	10th grade
MON 10:30	History	Physics
	I. Jones	M. Curie
	10th grade	9th grade
…

应用程序将使用AI自动为每个Timeslot和Room分配Lesson实例，以符合硬约束和软约束的调度要求，例如：

一个教室在同一时间只能有一个课程。

一个老师在同一时间只能上一节课。

一个学生在同一时间只能参加一门课。

老师更喜欢在同一个教室上所有的课。

老师更喜欢连续的课，并且不喜欢课之间的间隔。

学生不喜欢相同科目的连续课。

从数学角度来看，学校课程安排是一个NP困难问题。这意味着它很难扩展。即使在超级计算机上，仅通过遍历所有可能的组合也需要数百万年才能处理非平凡的数据集。幸运的是，像OptaPlanner这样的AI约束求解器具有先进的算法，可以在合理的时间内提供接近最优的解决方案。

2. 解决方案源代码

按照下面的步骤创建应用程序（推荐）。

或者查看已完成的示例：

完成以下任务之一：

克隆Git存储库：

$ git clone https://github.com/kiegroup/optaplanner-quickstarts

下载存档。

在hello-world目录中找到解决方案。

按照README文件中的说明运行应用程序。

3. 先决条件

要完成本指南，您需要：

配置了JAVA_HOME的JDK 11+

Apache Maven 3.8.1+或Gradle 4+

IDE，如IntelliJ IDEA、VSCode或Eclipse

4. 构建文件和依赖项

创建一个Maven或Gradle构建文件，并添加以下依赖项：

optaplanner-core（compile scope）用于解决学校课程表问题。

optaplanner-test（test scope）用于对学校课程安排约束进行JUnit测试。

一个日志记录实现，例如logback-classic（runtime scope），以查看OptaPlanner正在执行的操作。

如果选择使用Maven，您的pom.xml文件应具有以下内容：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

  <groupId>org.acme</groupId>
  <artifactId>optaplanner-hello-world-school-timetabling-quickstart</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.release>11</maven.compiler.release>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.optaplanner</groupId>
        <artifactId>optaplanner-bom</artifactId>
        <version>9.44.0.Final</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
      <dependency>
        <groupId>ch.qos.logback</groupId>
        <artifactId>logback-classic</artifactId>
        <version>1.2.3</version>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-core</artifactId>
    </dependency>
    <dependency>
      <groupId>ch.qos.logback</groupId>
      <artifactId>logback-classic</artifactId>
      <scope>runtime</scope>
    </dependency>

    <!-- Testing -->
    <dependency>
      <groupId>org.optaplanner</groupId>
      <artifactId>optaplanner-test</artifactId>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>exec-maven-plugin</artifactId>
        <version>3.0.0</version>
        <configuration>
          <mainClass>org.acme.schooltimetabling.TimeTableApp</mainClass>
        </configuration>
      </plugin>
    </plugins>
  </build>
</project>

另一方面，如果选择使用Gradle，您的build.gradle文件应具有以下内容：

plugins {
   
    id "java"
    id "application"
}

def optaplannerVersion = "9.44.0.Final"
def logbackVersion = "1.2.9"

group = "org.acme"
version = "1.0-SNAPSHOT"

repositories {
   
    mavenCentral()
}

dependencies {
   
    implementation platform("org.optaplanner:optaplanner-bom:${
     optaplannerVersion}")
    implementation "org.optaplanner:optaplanner-core"
    testImplementation "org.optaplanner:optaplanner-test"

    runtimeOnly "ch.qos.logback:logback-classic:${
     logbackVersion}"
}

java {
   
    sourceCompatibility = JavaVersion.VERSION_11
    targetCompatibility = JavaVersion.VERSION_11
}

compileJava {
   
    options.encoding = "UTF-8"
    options.compilerArgs << "-parameters"
}

compileTestJava {
   
    options.encoding = "UTF-8"
}

application {
   
    mainClass = "org.acme.schooltimetabling.TimeTableApp"
}

test {
   
    // Log the test execution results.
    testLogging {
   
        events "passed", "skipped", "failed"
    }
}

5. 建模领域对象

您的目标是为每节课分配一个时间槽和一个教室。您将创建以下类：

5.1. Timeslot

Timeslot类表示上课的时间间隔，例如，星期一10:30-11:30或星期二13:30-14:30。为了简单起见，所有时间段的持续时间都相同，午餐或其他休息时间段中没有时间槽。

时间槽没有日期，因为高中的课程表每周都会重复。因此，不需要连续规划。

创建src/main/java/org/acme/schooltimetabling/domain/Timeslot.java类：

package org.acme.schooltimetabling.domain;

import java.time.DayOfWeek;
import java.time.LocalTime;

public class Timeslot {
   

    private DayOfWeek dayOfWeek;
    private LocalTime startTime;
    private LocalTime endTime;

    public Timeslot() {
   
    }

    public Timeslot(DayOfWeek dayOfWeek, LocalTime startTime, LocalTime endTime) {
   
        this.dayOfWeek = dayOfWeek;
        this.startTime = startTime;
        this.endTime = endTime;
    }

    public DayOfWeek getDayOfWeek() {
   
        return dayOfWeek;
    }

    public LocalTime getStartTime() {
   
        return startTime;
    }

    public LocalTime getEndTime() {
   
        return endTime;
    }

    @Override
    public String toString() {
   
        return dayOfWeek + " " + startTime;
    }

}

由于在求解过程中Timeslot实例不会改变，因此Timeslot被称为问题事实。这些类不需要任何OptaPlanner特定的注解。

注意toString()方法保持输出简洁，以便更容易阅读OptaPlanner的DEBUG或TRACE日志，如下所示。

5.2. Room

Room类表示上课的地点，例如，教室A或教室B。为了简单起见，所有教室都没有容量限制，可以容纳所有课程。

创建src/main/java/org/acme/schooltimetabling/domain/Room.java类：

package org.acme.schooltimetabling.domain;

public class Room {
   

    private String name;

    public Room() {
   
    }

    public Room(String name) {
   
        this.name = name;
    }

    public String getName() {
   
        return name;
    }

    @Override
    public String toString() {
   
        return name;
    }

}

Room实例在求解过程中不会改变，因此Room也是一个问题事实。

5.3. Lesson

Lesson类表示一节课，其中教师向一群学生教授某个科目，例如，A.Turing的9年级数学课或M.Curie的10年级化学课。如果同一个教师每周多次教授同一学生组的某门科目，则存在多个只能通过id区分的Lesson实例。例如，9年级每周有六节数学课。

在求解过程中，OptaPlanner会更改Lesson类的timeslot和room字段，以将每节课分配到一个时间槽和一个教室。由于OptaPlanner更改了这些字段，Lesson是一个计划实体：

前面图表中的大多数字段都包含输入数据，除了橙色字段：输入数据中的课程的timeslot和room字段未分配（null），输出数据中已分配（非null）。OptaPlanner在求解过程中更改这些字段。此类字段称为计划变量。为了让OptaPlanner识别它们，timeslot和room字段都需要@PlanningVariable注解。它们所属的类Lesson需要一个@PlanningEntity注解。

创建src/main/java/org/acme/schooltimetabling/domain/Lesson.java类：

package org.acme.schooltimetabling.domain;

import org.optaplanner.core.api.domain.entity.PlanningEntity;
import org.optaplanner.core.api.domain.lookup.PlanningId;
import org.optaplanner.core.api.domain.variable.PlanningVariable;

@PlanningEntity
public class Lesson {
   

    @PlanningId
    private Long id;

    private String subject;
    private String teacher;
    private String studentGroup;

    @PlanningVariable
    private Timeslot timeslot;
    @PlanningVariable
    private Room room;

    public Lesson() {
   
    }

    public Lesson(Long id, String subject, String teacher, String studentGroup) {
   
        this.id = id;
        this.subject = subject;
        this.teacher = teacher;
        this.studentGroup = studentGroup;
    }

    public Long getId() {
   
        return id;
    }

    public String getSubject() {
   
        return subject;
    }

    public String getTeacher() {
   
        return teacher;
    }

    public String getStudentGroup() {
   
        return studentGroup;
    }

    public Timeslot getTimeslot() {
   
        return timeslot;
    }

    public void setTimeslot(Timeslot timeslot) {
   
        this.timeslot = timeslot;
    }

    public Room getRoom() {
   
        return room;
    }

    public void setRoom(Room room) {
   
        this.room = room;
    }

    @Override
    public String toString() {
   
        return subject + "(" + id + ")";
    }

}

Lesson类具有@PlanningEntity注解，因此OptaPlanner知道该类在求解过程中会发生变化，因为它包含一个或多个计划变量。

timeslot字段具有@PlanningVariable注解，因此OptaPlanner知道它可以更改其值。为了找到可分配给该字段的潜在Timeslot实例，OptaPlanner使用变量类型连接到值范围提供程序