<commit_before><?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xml:id="designPatterns" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Design Patterns</title>

  <section xml:id="designPatternsIntroduction">
    <title>Design Patterns Introduction</title>

    <para>These design patterns solve common design challenges and name them.</para>
  </section>

  <section xml:id="assigningTimeToPlanningEntities">
    <title>Assigning Time to Planning Entities</title>

    <para>Dealing with time and dates in planning problems can be confusing and it depends on the needs of your use
    case.</para>

    <para>There are several representations of timestamps, dates, durations and periods in Java. Choose the right
    representation type for your use case:</para>

    <itemizedlist>
      <listitem>
        <para><literal>java.util.Date</literal> (deprecated): an slow, error-prone way to represent timestamps. Do not
        use.</para>
      </listitem>

      <listitem>
        <para><literal>javax.time.LocalDateTime</literal>, <literal>LocalDate</literal>, <literal>DayOfWeek</literal>,
        <literal>Duration</literal>, <literal>Period</literal>, ...: an accurate way to represent and calculate with
        timestamps, dates, ...</para>

        <itemizedlist>
          <listitem>
            <para>Also has support for timezones and DST (Daylight Saving Time) if needed.</para>
          </listitem>

          <listitem>
            <para>Requires Java 8 or higher.</para>

            <itemizedlist>
              <listitem>
                <para>On Java 7 use its backport called <emphasis>ThreeTen Backport</emphasis> instead.</para>
              </listitem>

              <listitem>
                <para>On Java 6 or lower, use its predecessor called <emphasis>Joda Time</emphasis> instead.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><literal>int</literal> or <literal>long</literal>: Cache a timestamp as a simplified number of
        course-grained time units (such as minutes) from the start of the global planning time window or the
        epoch.</para>

        <itemizedlist>
          <listitem>
            <para>For example: a <literal>LocalDateTime</literal> of <literal>1-JAN 08:00:00</literal> becomes an
            <literal>int</literal> of <literal>400</literal> minutes. Similarly <literal>1-JAN 09:00:00</literal>
            becomes <literal>460</literal> minutes.</para>
          </listitem>

          <listitem>
            <para>Often an extra field in an class alongside the <literal>LocalDateTime</literal> field it was
            calculated from. The <literal>LocalDateTime</literal> is used for user visualization, but the
            <literal>int</literal> is used in the score constraints.</para>
          </listitem>

          <listitem>
            <para>Faster in calculations. Especially useful well in the TimeGrain pattern.</para>
          </listitem>

          <listitem>
            <para>Do not use if timezones or DST affect the score constraints.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>

    <para>There are also several designs for assigning a planning entity to a starting time (or date):</para>

    <itemizedlist>
      <listitem>
        <para>The starting time is fixed beforehand. It's not a planning variable (in this solver).</para>

        <itemizedlist>
          <listitem>
            <para>For example, in <link linkend="bedAllocation">the hospital bed planning</link> example, the arrival
            day of each patient is fixed beforehand.</para>
          </listitem>

          <listitem>
            <para>This is common in <link linkend="multiStagePlanning">multi stage planning</link>, when an earlier
            planning stage already decided the starting time.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>The starting time is not fixed, it is a planning variable (genuine or shadow).</para>

        <itemizedlist>
          <listitem>
            <para>If all planning entities have the same duration, use <link linkend="timeslotPattern">the Timeslot
            pattern</link>.</para>

            <itemizedlist>
              <listitem>
                <para>For example in course scheduling, all lectures take 1 hour. Each timeslot is 1 hour.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>If duration differs and time uses a course-grained granularity such as 5 minutes (or more) use <link
            linkend="timeGrainPattern">the TimeGrain pattern</link>.</para>

            <itemizedlist>
              <listitem>
                <para>For example in meeting scheduling, all meetings start at 15 minute intervals. All meetings take
                15, 30, 45, 60, 90 or 120 minutes.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>If duration differs and one task starts immediately after the previous task (assigned to the same
            executor) finishes, use <link linkend="???">the Chained Through Time pattern</link>.</para>

            <itemizedlist>
              <listitem>
                <para>For example in time windowed vehicle routing, each vehicle departs immediately to the next
                customer when the delivery on the previous customer finishes.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>

    <para>Choose the right pattern depending on the use case:</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/Chapter-Design_patterns/assigningTimeToPlanningEntities.png"/>
      </imageobject>
    </mediaobject>

    <section xml:id="timeslotPattern">
      <title>Timeslot Pattern: Assign to a Fixed-Length Timeslot</title>

      <para>TODO</para>
    </section>

    <section xml:id="timeGrainPattern">
      <title>TimeGrain Pattern: Assign to a Starting TimeGrain</title>

      <para>TODO</para>
    </section>

    <section xml:id="chainedThroughTime">
      <title>Chained Through Time Pattern: Assign in a Chain that Determines Starting Time</title>

      <para>TODO</para>

      <para>No variable gaps. Deterministic gaps are ok.</para>
    </section>
  </section>

  <section xml:id="multiStragePlanning">
    <title>Multi stage planning</title>

    <para>For practical or organizational reasons (such as Conway's law), complex planning problems are often broken
    down in multiple stages. A typical example is train scheduling, where one department decides where and when a train
    will arrive/depart, and another departments assigns the operators and actual train cars/locomotives.</para>

    <para>Each stage has its own solver configuration (and therefore its own <literal>SolverFactory</literal>). Do not<commit_msg>docs time patterns<commit_after><?xml version="1.0" encoding="UTF-8"?>
<chapter version="5.0"
         xsi:schemaLocation="http://docbook.org/ns/docbook http://www.docbook.org/xml/5.0/xsd/docbook.xsd http://www.w3.org/1999/xlink http://www.docbook.org/xml/5.0/xsd/xlink.xsd"
         xml:base="../" xml:id="designPatterns" xmlns="http://docbook.org/ns/docbook"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xs="http://www.w3.org/2001/XMLSchema"
         xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude"
         xmlns:ns="http://docbook.org/ns/docbook">
  <title>Design Patterns</title>

  <section xml:id="designPatternsIntroduction">
    <title>Design Patterns Introduction</title>

    <para>These design patterns solve common design challenges and name them.</para>
  </section>

  <section xml:id="assigningTimeToPlanningEntities">
    <title>Assigning Time to Planning Entities</title>

    <para>Dealing with time and dates in planning problems can be confusing and it depends on the needs of your use
    case.</para>

    <para>There are several representations of timestamps, dates, durations and periods in Java. Choose the right
    representation type for your use case:</para>

    <itemizedlist>
      <listitem>
        <para><literal>java.util.Date</literal> (deprecated): an slow, error-prone way to represent timestamps. Do not
        use.</para>
      </listitem>

      <listitem>
        <para><literal>javax.time.LocalDateTime</literal>, <literal>LocalDate</literal>, <literal>DayOfWeek</literal>,
        <literal>Duration</literal>, <literal>Period</literal>, ...: an accurate way to represent and calculate with
        timestamps, dates, ...</para>

        <itemizedlist>
          <listitem>
            <para>Also has support for timezones and DST (Daylight Saving Time) if needed.</para>
          </listitem>

          <listitem>
            <para>Requires Java 8 or higher.</para>

            <itemizedlist>
              <listitem>
                <para>On Java 7 use its backport called <emphasis>ThreeTen Backport</emphasis> instead.</para>
              </listitem>

              <listitem>
                <para>On Java 6 or lower, use its predecessor called <emphasis>Joda Time</emphasis> instead.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para><literal>int</literal> or <literal>long</literal>: Cache a timestamp as a simplified number of
        course-grained time units (such as minutes) from the start of the global planning time window or the
        epoch.</para>

        <itemizedlist>
          <listitem>
            <para>For example: a <literal>LocalDateTime</literal> of <literal>1-JAN 08:00:00</literal> becomes an
            <literal>int</literal> of <literal>400</literal> minutes. Similarly <literal>1-JAN 09:00:00</literal>
            becomes <literal>460</literal> minutes.</para>
          </listitem>

          <listitem>
            <para>Often an extra field in an class alongside the <literal>LocalDateTime</literal> field it was
            calculated from. The <literal>LocalDateTime</literal> is used for user visualization, but the
            <literal>int</literal> is used in the score constraints.</para>
          </listitem>

          <listitem>
            <para>Faster in calculations. Especially useful well in the TimeGrain pattern.</para>
          </listitem>

          <listitem>
            <para>Do not use if timezones or DST affect the score constraints.</para>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>

    <para>There are also several designs for assigning a planning entity to a starting time (or date):</para>

    <itemizedlist>
      <listitem>
        <para>The starting time is fixed beforehand. It's not a planning variable (in this solver).</para>

        <itemizedlist>
          <listitem>
            <para>For example, in <link linkend="bedAllocation">the hospital bed planning</link> example, the arrival
            day of each patient is fixed beforehand.</para>
          </listitem>

          <listitem>
            <para>This is common in <link linkend="multiStagePlanning">multi stage planning</link>, when an earlier
            planning stage already decided the starting time.</para>
          </listitem>
        </itemizedlist>
      </listitem>

      <listitem>
        <para>The starting time is not fixed, it is a planning variable (genuine or shadow).</para>

        <itemizedlist>
          <listitem>
            <para>If all planning entities have the same duration, use <link linkend="timeslotPattern">the Timeslot
            pattern</link>.</para>

            <itemizedlist>
              <listitem>
                <para>For example in course scheduling, all lectures take 1 hour. Each timeslot is 1 hour.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>If duration differs and time is rounded to a specifc time granularity (for example 5 minutes) use
            <link linkend="timeGrainPattern">the TimeGrain pattern</link>.</para>

            <itemizedlist>
              <listitem>
                <para>For example in meeting scheduling, all meetings start at 15 minute intervals. All meetings take
                15, 30, 45, 60, 90 or 120 minutes.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>If duration differs and one task starts immediately after the previous task (assigned to the same
            executor) finishes, use <link linkend="???">the Chained Through Time pattern</link>.</para>

            <itemizedlist>
              <listitem>
                <para>For example in time windowed vehicle routing, each vehicle departs immediately to the next
                customer when the delivery on the previous customer finishes.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>
      </listitem>
    </itemizedlist>

    <para>Choose the right pattern depending on the use case:</para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/Chapter-Design_patterns/assigningTimeToPlanningEntities.png"/>
      </imageobject>
    </mediaobject>

    <section xml:id="timeslotPattern">
      <title>Timeslot Pattern: Assign to a Fixed-Length Timeslot</title>

      <para>If all planning entities have the same duration (or can be inflated to the same duration), the Timeslot
      pattern is useful. The planning entities are assigned to a timeslot, instead of a loose time. For example in the
      course scheduling example, all lectures take 1 hour and they can start at 8:00, 9:00, 10:15, 11:15, 13:30,
      ...</para>

      <para>It is also usable if all planning entities can be inflated to the same duration. For example in the exam
      scheduling example, some exams take 90 minutes and others 120 minutes, but all timeslots are 120 minutes. When an
      exam of 90 minutes is assigned to a timeslot, the remaining 30 minutes is gone too and cannot be used by another
      exam.</para>
    </section>

    <section xml:id="timeGrainPattern">
      <title>TimeGrain Pattern: Assign to a Starting TimeGrain</title>

      <para>Assigning humans to start a meeting at 4 seconds after 9 o'clock is pointless because a second accuracy on
      meetings starts is overly optimistic. Most human activities have a time granularity of 5 minutes or 15 minutes.
      Therefore it's unneeded to allow a planning entity to be assigned on subsecond, second or even 1 minute accuracy,
      if 5 minute or 15 minutes accuracy suffices. For example in the meeting scheduling example, all meetings start and
      end on the hour, half hour or 15 minutes before/after the hour.</para>

      <para>In the TimeGrain pattern, each planning entities is assigned to a starting time grain. The ending time grain
      is calculated by adding the duration in grains to the starting time grain. Overlap of 2 entities is determined by
      comparing their start and end time grains.</para>

      <para>This pattern also works with a coarser time granularity (such as days, half days, hours, ...). With a finer
      time granularity (such as seconds, milliseconds, ...) and a long planning window, the value range (and therefore
      <link linkend="searchSpaceSize">the search space</link>) can become very big which reduces efficiency and
      scalability.</para>
    </section>

    <section xml:id="chainedThroughTime">
      <title>Chained Through Time Pattern: Assign in a Chain that Determines Starting Time</title>

      <para>If a person or machine continuously works on 1 task at a time, starting a task when the previous is finished
      (or with a deterministic delay), the Chained Through Time pattern is usefull. For example, in the vehicle routing
      with time windows example, a vehicle drives from customer to customer (so he handles 1 customer at a time).</para>

      <para>In this pattern, the planning entities are <link linkend="chainedPlanningVariable">chained</link>. The
      anchor determines the starting time of its first planning entity. The second entity's starting time is calculated
      based on the starting time and duration of the first entity. For example, in task assignment, Beth (the anchor)
      starts working at 8:00, so her first task starts at 8:00. It lasts 52 mins. At 8:52 her second task starts. The
      starting time is usually <link linkend="shadowVariable">a shadow variable</link>.</para>

      <para>Between planning entities, there no gaps or only deterministic gaps.</para>
    </section>
  </section>

  <section xml:id="multiStragePlanning">
    <title>Multi stage planning</title>

    <para>For practical or organizational reasons (such as Conway's law), complex planning problems are often broken
    down in multiple stages. A typical example is train scheduling, where one department decides where and when a train
    will arrive/depart, and another departments assigns the operators and actual train cars/locomotives.</para>

    <para>Each stage has its own solver configuration (and therefore its own <literal>SolverFactory</literal>). Do not
{'fraction_non_alphanumeric': 0.09784485158990923, 'fraction_numerical': 0.011471849418054242, 'mean_word_length': 2.6529698942229456, 'pattern_counts': {'":': 0, '<': 431, '<?xml version=': 2, '>': 431, 'https://': 0, 'lorem ipsum': 0, 'www.': 14, 'xml': 34}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7254582', 'n_tokens_mistral': 5005, 'n_tokens_neox': 4674, 'n_words': 1711}