14 KiB
Personal Leave Planning
VacOptimizer helps one person turn expiring leave balances into a leave plan across a planning horizon. It combines leave placements with declared non-working days, weekends, French public holidays, and ordered planning rules, then reports the resulting time-off periods and any unplaced balances.
Language
Leave entitlement: A quantity of leave granted by a company or generated by an applicable planning rule, with an availability date and an expiry date.
Leave balance: The unspent quantity of a leave entitlement, identified by leave type, availability date, and expiry date. Reported balances are assumed current on the calculation's Europe/Paris calendar date, with booked leave already deducted and earned entitlements available by that date already included. Avoid: vacation day, VacDay
At-risk balance: A leave balance whose expiry date falls between the planning horizon's start and end, including both boundary dates. Its unplaced quantity is at risk of being lost.
Unavoidable expiry: Leave whose expiry date precedes the planning horizon and therefore cannot be saved by that plan.
Deferred balance: The unspent portion of a leave balance that expires after the planning horizon. It needs no ordinary placement in the current plan but remains available to explicit planning rules and supporting placements.
Leave type:
The category of leave in a balance or on a declared non-working day: CP (paid leave), RTT (working-time reduction leave), or Other (a user-managed catch-all, including any other reason for not working).
Avoid: ANY as a leave type; ANY is only a rule selector.
Planning horizon: The user-selected half-open date interval within which leave may be placed; its start may precede today's Europe/Paris calendar date and its duration may exceed twelve months. It defaults to today through the same date twelve months later, and explicitly selected boundaries remain unchanged as time passes, with past dates still eligible for leave placements.
Last planning date: The inclusive final calendar date selected by the user for leave placement; the planning horizon's exclusive end is the following calendar date. Avoid: horizon end
Working day: A Monday-to-Friday calendar date that is not a French national public holiday. New leave placements are restricted to working days that have not been declared non-working.
Declared non-working day: A working day on which the user declares they will not work, identified by a CP, RTT, or Other leave type. Its date and type are fixed during planning; it consumes no remaining leave balance and contributes to compatible planning rules.
Public holiday: A French calendar date that cannot receive a leave placement and contributes to a time-off period.
Public holiday connected to a weekend: A distinct Monday-to-Friday public-holiday date in a planned time-off period containing at least one Saturday or Sunday, including adjacent holiday dates outside the planning horizon; the connection may be direct or through leave placements or declared non-working days. Weekend public holidays and naturally long weekends without a leave placement or declared non-working day are excluded.
Public-holiday week: A Monday-to-Friday window containing a weekday French public holiday where every other working day is a leave placement or declared non-working day.
Public-holiday week value: The distance of every weekday holiday from the nearest weekend, summed within and across completed public-holiday weeks: Monday or Friday is 1, Tuesday or Thursday is 2, and Wednesday is 3.
Leave placement: Using one or more working days from a leave balance on specific dates within the planning horizon.
Supporting placement: A leave placement from a deferred balance that completes a public-holiday week, captures additional adjacent non-working dates, eliminates a short work sequence, or reduces the longest work sequence. Merely extending an existing period by the placed day itself is not sufficient.
Time-off period: A contiguous period containing at least one leave placement or declared non-working day, together with any adjacent non-working dates, including those immediately outside the planning horizon. Avoid: leave sequence
Time-off duration: The number of distinct calendar dates covered by all planned time-off periods.
Average time-off period length: The arithmetic mean duration in calendar days of all planned time-off periods, including adjacent non-working dates outside the planning horizon.
Longest time-off period length: The greatest duration in calendar days among the planned time-off periods, including adjacent non-working dates outside the planning horizon.
Non-working-day gain: The distinct weekend and public-holiday dates contained in planned time-off periods. Leave placement dates themselves do not contribute to this gain.
Work sequence: The working days in an interval delimited by planned time-off periods or by the planning horizon edges. Intervening weekends and public holidays neither count nor split the sequence.
Average work-sequence length: The arithmetic mean number of working days across all non-empty work sequences within the planning horizon, including the sequences before the first time-off period and after the last.
Longest work-sequence length: The greatest number of working days in any work sequence within the planning horizon, including the sequences at both horizon edges.
Short work sequence: A work sequence of fewer than five working days between two planned time-off periods.
Short work-sequence deficit: The total number of working days missing for all short work sequences to reach five working days each; empty sequences contribute zero.
Week with one workday: An undesirable Monday-to-Sunday calendar week with exactly one working day remaining after excluding leave placements and declared non-working days. All five Monday-to-Friday dates must fall within the planning horizon.
Planning rule: A named instruction, supplied by the application or defined by the user, that guides leave placement. Only enabled rules influence the plan, and each rule's force is either an obligation or a preference.
Optimization rule: A preference rule that minimizes or maximizes a measure over selected planning elements, such as leave balances, time-off periods, or work sequences.
Optimization rule preset: A predefined optimization rule configuration supplied by the application that the user can use as an editable planning rule.
Loss prevention rule: An optimization rule that minimizes unplaced at-risk leave.
Obligation rule: A planning rule that every valid plan must satisfy. Obligation rules are resolved jointly; their order only breaks ties between valid plans.
Preference rule: A planning rule that guides placement but may remain unsatisfied to preserve validity or satisfy higher-priority preferences.
IF_THEN rule: A planning rule evaluated independently for every French public holiday on its configured weekday. A preference requests a complete pattern around each occurrence when possible; an obligation requires it for every occurrence.
IF_THEN placement mode:
before and after fix every requested day on one side; around considers every split with at least one day on each side; auto considers every split, including the all-before and all-after extremes.
TIME_WINDOW rule: A planning rule counting compatible leave placements and declared non-working days in an inclusive date window. A preference requests up to its configured quantity; an obligation requires exactly that quantity.
Rule priority: The user-defined lexicographic order shared by all active preference rules, including optimization rules. Each earlier preference is satisfied as far as possible before a later preference is considered.
Rule satisfaction: The relationship in which a plan fulfils a planning rule. One compatible leave placement or declared non-working day may contribute to the satisfaction of multiple rules.
Placement provenance: The consumed leave entitlement and every planning rule satisfied by a leave placement.
Plan statistics: The numerical summary of a calculated valid plan's leave usage, time-off periods, and work patterns, including a valid plan retained by an incomplete calculation. It reflects that calculation's horizon, balances, rules, declared non-working days, and Europe/Paris calendar date.
Plan explanation: A stable account of why an optimization result or incomplete calculation contains its displayed leave placements, expressed through placement provenance, planning objectives, time-off periods, and remaining balances. It reports every contribution of a placement while highlighting the first planning objective that made its position decisive, and describes the displayed plan rather than the calculation history. Avoid: calculation explanation
Calculation trace: The complete, untruncated, ordered history of the planning decisions and candidate evaluations from the same calculation that produced a planning outcome, grouped by calculation phase. It is not reconstructed by replaying the calculation afterward; for an incomplete calculation it ends at the actual interruption point. Avoid: plan explanation
Planning decision: An atomic choice within a calculation phase that accepts, moves, removes, or rejects one or more related leave placements. A joint obligation decision may therefore concern several dates. Avoid: calendar day, step
Candidate evaluation: The comparison the planner actually performs between a possible leave-placement change and the current plan. It belongs to the calculation trace whether the candidate is accepted or rejected.
Candidate date status: The historical relationship between a date and a planning decision: chosen, evaluated and rejected, not examined, or ineligible with a reason. A later counterfactual date analysis never changes this historical status.
Counterfactual date analysis: An on-demand evaluation that changes only the date of one selected leave placement while preserving its leave balance, leave type, and placement provenance. The planner did not necessarily examine that date; the analysis explains a hypothetical alternative but never influences the planning outcome and is not part of the calculation trace. Avoid: candidate evaluation, calculation trace
Conflict explanation: A stable account of why no plan can jointly satisfy a set of obligation rules within the planning horizon and available leave balances. Avoid: plan explanation
Planning conflict: A set of obligation rules that cannot all be satisfied by one plan within the planning horizon and available leave balances.
Invalid planning input: A malformed request that cannot describe a plan, such as a reversed date window. A valid but unsatisfiable request is a planning conflict instead.
Planning outcome: The result of a calculation: invalid input, a planning conflict, an optimization result, or an incomplete calculation.
Stable plan explanation: A deterministic explanation derived from the final displayed plan. It identifies each placement's entitlement and rule provenance, contributions, full objective vector, and the first objective that distinguishes the plan with that placement restored from the same plan with only that placement removed.
Original decision trace: The untruncated phase-by-phase record captured by the calculation that produced the displayed outcome, including atomic decisions, candidate statuses, and state deltas. It is historical evidence and is never recomputed from the final plan.
Counterfactual date analysis: A hypothetical comparison that keeps the calculation snapshot and all unrelated placements fixed while testing one selected placement across every date in the half-open planning horizon. It neither mutates the plan nor rewrites the original trace.
Incomplete calculation: A calculation stopped by user cancellation or another interruption before it completed the planning objective order. On user cancellation it exposes its best available valid plan as partial, if one exists, and never implies that the obligations conflict.
Planning objective order: The lexicographic quality order applied after joint obligation feasibility, with active preference rules, including optimization rules, sharing the user-defined rule priority. A lower criterion never degrades a higher one.
Earned leave: The total quantity of earned leave entitlements generated by all applicable planning rules for a plan, counted before consumption and attributed to their generating rules. Only entitlements becoming available strictly after the calculation's Europe/Paris calendar date qualify, including those becoming available after the planning horizon.
Earned leave entitlement: A leave entitlement earned for each completed occurrence of an applicable planning rule after its generating time-off period ends, whether that occurrence is fulfilled by leave placements, declared non-working days, or both. It becomes available the following day, expires one year later, and may fund later compatible placements; only entitlements becoming available after the calculation's Europe/Paris calendar date are added to the plan. Avoid: reward, bonus days
Optimization result: A valid deterministic plan produced after completing the planning objective order, containing declared non-working days, leave placements and their provenance, time-off periods, unsatisfied preference reasons, and remaining balances with reasons. It does not claim mathematical global optimality.
Remaining balance: Any quantity left unspent by the optimization result, reported as unavoidable expiry, an unplaced at-risk balance, or a deferred balance.
Non-placement reason: A concrete explanation of why a quantity of a leave balance remains unspent in the displayed plan, distinguishing a blocking condition from a decision to preserve leave for later. It includes the relevant dates, is distinct from the balance's expiry-based classification, and can be supported by recorded candidate evaluations.