.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  workflow_dispatch:
+  push:
+  pull_request:
+  release:
+
+permissions:
+  contents: read
+
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v4
+
+      - name: Setup JDK
+        uses: actions/setup-java@v4
+        with:
+          java-version: 21
+          distribution: temurin
+          cache: sbt
+
+      - name: Setup sbt
+        uses: sbt/setup-sbt@v1
+
+      - name: Clean compile
+        run: sbt clean
+
+      - name: Run fast tests
+        run: sbt test
+
+      - name: Run slow tests
+        run: sbt test-slow:test

.gitignore

@@ -12,13 +12,22 @@ lib_managed/
 src_managed/
 project/boot/
 project/plugins/project/
+project/**/target
 
 # BSP
 .bsp
 
+# Metals
+.metals
+project/metals.sbt
+project/**/metals.sbt
+
 # Scala-IDE specific
 .scala_dependencies
 .worksheet
 
 # IntelliJ specific
 .idea
+
+# VSCode specific
+.vscode

IDEAS.md

@@ -0,0 +1,8 @@
+- Add unit test for forced topics
+- When a schedule is a success (better than previous one), try to re-assign everyone a few times to see if you can improve it further
+- Better handling of constraints
+- Incompatibility reward should be in the preference (in the config), not in settings
+- Create a max-unassigned or max-nothing, and use a topic-exclusive ? It's not a personal pref though, so it doesn't work that well
+- Keep and display schedules that are close to the current one, to give some alternatives (or fix a target score and give all that are above the score)
+- Simulated cooling
+- Generate a better base configuration, depending on what the user asks for

README.md

@@ -30,35 +30,45 @@ The input file describes the problem to solve. It follows the HOCON format, and
 
 - `gaston`: Root element of the configuration.
     - `settings`: Global settings. All fields are optional and have a default value.
+        - `status-display-interval`: How often you want to display new good schedules. You can write any time unit, for example: `20 seconds` or `30 minutes`, or abbreviate it as `20s` or `30m`. Default is `20 seconds`.
         - `incompatibility-anti-preference`: Negative score for a person forced to share a topic with someone it would rather not. Default is `-1000`.
         - `default-max-topics-per-slot`: Max number of topics per slot (default is no limit.
-        - `default-min-persons-per-topic`: Minimum number of persons per topic, can be overriden on specific topics. Default is `1`.
-        - `default-max-persons-per-topic`: Maximum number of persons per topic, can be overriden on specific topics. Default is `10`.
-        - `max-persons-on-nothing`: On each slot, maximum number of persons who can have no topic scheduled. Default value is `0`, i.e. everyone must have a topic scheduled on each slot.
-        - `min-persons-on-nothing`: On each slot, minimum number of persons who can have no topic scheduled (the idea being that enough unoccupied persons can do something together). Default is `0`, i.e. no minimum.
-        - `person-on-nothing-anti-preference`: Negative score attached to a person doing nothing on a slot. Default value is `-100`.
-        - `backtrack-initial-schedule`: Technical stuff: should initial schedules be empty or backtracked ? Best answer depends on the schedule being highly constrained or note. Default is `true`.
+        - `default-min-persons-per-topic`: Minimum number of persons per topic, can be overridden on specific topics. Default is `1`.
+        - `default-max-persons-per-topic`: Maximum number of persons per topic, can be overridden on specific topics. Default is `10`.
+        - `unassigned`: A bunch of settings about how to handle unassigned persons (to be unassigned is to not be scheduled on any topic, on some slot). Default is no not allow it at all.
+            - `allowed`: If true, Gaston will allow for people staying unassigned. Default is `false`.
+            - `person-anti-preference`: Negative score attached to a person being unassigned. It's counted once for every slot when a person is unassigned. Default value is `-1000`.
+            - `person-multiple-anti-preference`: Additional negative score attached if unassigned on multiple slots (in addition to the basic anti-preference). Useful if you want to make one unassignment acceptable, but not two. Default value is `0`.
+            - `max`: On each slot, maximum number of persons who can be unassigned. Default is unlimited.
+            - `min`: On each slot, minimum number of persons who can be unassigned (the idea being that enough unassigned persons can do something together). Default is `0`, i.e. no minimum.
+            - `persons-anti-preference-scaling`: If present, this settings make the unassignment anti-preference scale with the number of forbidden entries of a person. The more topics are forbidden for them, the less impactful an unassignment will be. Default is none.
+                - `forbidden-ratio-for-maximum`: For a person, if their ratio of forbidden topics to total topics reach this value, the unassignment anti-preference will be set to its maximum value below.Default is `75%`.
+                - `maximum-anti-preference`: If a person has the maximum ratio of forbidden topics, their unassignment anti-preference. Default is `-1`.
+        - `absence-adjustment-factor`: If a person is absent, with a factor of 1, its score will be adjusted so that it will be the same as someone having the same % of their time on the same wish level. For example: if you're only present on 3 slots and have 3 wishes at 5, you'll have the same score than someone present on 5 slots and 3 wishes at 5. This factor lets you reduce that a bit. Putting a lower factor means that absence counts for less than 1, leading to slightly better schedules for people who are missing some slots. The reasoning: if they're not here as much, they should at least enjoy the slots they are here. 
     - `tableSettings`: Settings for importing a table. Optional (leave that field out if you are not importing a table). See the *Importing a table* section below for details. 
-    - `slots`: The slots on which to schedule, as an array of arrays of slots. The inner arrays contain the slots following each other directly (such as one in the morning and the other in the afternoon of the same day), so that mult-slot topics may be handled (WIP). The following lines describe the structure of one slot.
+    - `slots`: The slots on which to schedule, as an array of arrays of slots. The inner arrays contain the slots following each other directly (such as one in the morning and the other in the afternoon of the same day), so that mult-slot topics may be handled. The following lines describe the structure of one slot.
         - `name`: Name of the slot. Must be unique among slots.
         - `max-topics`: Maximum number of topics to schedule on this slot (e.g. because space as limited at that time).
     - `topics`: The topics to schedule. The following lines describe the structure of one topic.
         - `name`: Name of the topic. Must be unique among topics.
         - `min`: Minimum number of persons on a topic. Default is empty (will use the settings' value).
         - `max`: Maximum number of persons on a topic. Default is empty (will use the settings' value).
         - `occurrences`: How many sessions of the topic are possible. Default is `1`.
-        - `multiple`: How many parallel sessions this topic represents (all sessions are simultaneous). Note than min and max are for one session. Default is `1`.
+        - `duration`: How many consecutive slots the topic occupies. Default is `1`.
         - `slots`: An array of slot names on which the topic can be scheduled. Default is empty (can be scheduled on any slot).
         - `presence`: A score added for just having this topic present. Can be used to favor a topic, or to set a topic as to avoid if possible (with a negative score). Default is `0`.
         - `forced`: If `true`, this topic *must* be scheduled. Default is `false`.
     - `persons`: The persons to schedule. The following lines describe the structure of one person.
         - `name`: Name of the person. Must be unique among persons.
-        - `weight`: A person with a higher weight counts more when calculating the global score. Specifically, that person's individual score will be divided by its weight, bringing them down and making the schedule optimizing more for them.. Default is `1`.
+        - `weight`: A person with a higher weight counts more when calculating the global score. Specifically, that person's individual score will be divided by its weight, bringing them down and making the schedule optimizing more for them. Default is `1`.
+        - `base-score`: You can add a starting value for this person's score. This is useful only in very specific situations. Default is `0`.
         - `absences`: An array of slot names on which this person is missing, and therefore cannot be scheduled. Default is empty.
         - `mandatory`: An array of topic names for which this person is mandatory: it must be present on those topics. Default is empty.
         - `forbidden`: An array of topic names for which this person is forbidden: it cannot be scheduled on those topics. Default is empty.
         - `incompatible`: An array of person names this person wish not to share a topic with. Default is empty.
-        - `wishes`: A mapping of topic names to scores. The higher the score, the more that persons wishes to be on that topic. The scores will be rebalanced so that everyone has a 1000 points total.
+        - `wishes`: A mapping of topic names to scores. The higher the score, the more that persons wishes to be on that topic. The scores will be rebalanced so that everyone has a 1000 points total (including person wishes, next line).
+        - `personWishes`: A mapping of person names to scores. The higher the score, the more that persons wishes to be on a topic with the target person. The scores will be rebalanced so that everyone has a 1000 points total (including topic wishes, previous line).
+        - `min-free-slots`: How many free slots (slots where the person's not assigned to anything) they want. Implies that `unassigned` persons are allowed in the settings. Note that free slots must be on different slots sub-list (different days).
     - `constraints`: Global constraints on the schedule.
         - `simultaneous`: An array of simultaneity constraints.
             - `topics`: An array of topics. Those topics must all be scheduled on the same slot, or not at all.
@@ -236,8 +246,6 @@ gaston {
   
   settings {
       default-max-topics-per-slot = 3
-      minPersonsOnNothing = 3
-      maxPersonsOnNothing = 10
   }
   
   table-settings {
@@ -279,3 +287,42 @@ gaston {
   ]
 }
 ```
+
+
+# Developer's corner
+
+## Brain dump
+
+Some vocabulary:
+- Planning is when we decide which topic is on which slot. It does NOT include assigning persons to those topics or checking score. It does however require we check that mandatory persons are availabe.
+    - Therefore, a planning is a schedule with no one assigned apart from the mandatory persons.
+- Assignment is when we assign persons to an existing planning.
+- Scheduling is doing both.
+- An unfilled schedule is a schedule where only the planning is done, most persons are not assigned yet. Some persons may have been assigned, which is why we don't call it unassigned.
+
+The Engine produces a lazy list of schedules, each new schedule being better than the next one. The list ends when no
+further improvement can be found, which never happens on real-world examples. It starts with a seed for all random
+operations.
+
+The Engine is CPU-bound and monothreaded. Typically, you would run multiple Engines in parallel, one per CPU, with
+different seeds.
+
+An Engine run (in `Engine.lazySeq`) starts with an initial schedule respecting all constraints, but with probably a terrible score.
+- If using backtracking, a schedule with topics and such will be generated. If there are enough topics to occupy everyone and not too many constraints, that is the recommended solution.
+    - This uses the ScheduleGenerator, which is only used for this.
+    - This schedule has been assignment-optimized (see below).
+- If not using backtracking (backtrack-initial-schedule option is set to false), we start with an empty schedule. This is recommended if you expect some persons to be unassigned on some slots.
+    - This starts using `Schedule.startingUnassignedOrForced`.
+
+Then, the Engine generates a lazy-list by improving the state step-by-step.
+There are two Engines implemented, GreedyEngine and TabuSearchEngine. Only the first one is currently being used.
+
+In GreedyEngine, a generation step starts from the latest generated schedule, and procedes with the following steps:
+- Figure out all neighbours of the latest schedule in the planning spaces. Neighbours are plannings that we can get from that schedule by adding or dropping a topic, or swapping two topics.
+- Eliminate neighbours that would be just a revert of the previous change (e.g. latest schedule was obtained by adding topic A, then dropping topic A is not a neighbour we need to consider).
+- For each neighbour (lazily)
+  - Fills in the planning by assigning people to topics. We are respecting constraints (a person can't be on two topics in the same slot), but ignoring preferences (even strong ones).
+  - Improves the assignment as much as possible by swapping or moving persons around, stop when all moves make it worse.
+- As soon as we find a schedule that's better than the latest schedule, we stop iterating over neighbours and output that schedule.
+
+