Matrices date generation limitations

[hdinia]

Problem:

The current implementation of date generation in the Antares web faces limitations when dealing with non-conventional years. The main issues are:

1. start_date dependency: we generates dates based on the provided start date, using date-fns library to parse and increment dates. This approach works well for conventional calendar years but becomes problematic for custom Antares years that don't align with the calendar year.
2. configuration interdependence: when users change calendar parameters in the Configuration > General section, it affects the start date. This changes the date of January 1st in the generated sequence. This interdependence makes it difficult to maintain consistent date alignments across different configuration scenarios.
3. inflexibility with January 1st placement: the current method cannot force January 1st to fall on a specific day of the week when dealing with non-conventional years. This is because the date generation is linear and based solely on the start_date .
4. lack of back-calculation: the system doesn't have a mechanism to back-calculate dates to ensure specific alignments (e.g., making the Antares year start on a Saturday if January 1st is a Monday).

These limitations create several issues:

• The Antares year can start in any month, but this isn't properly handled in relation to January 1st and week alignments.
• January 1st needs to fall on a specific day of the week, but this is difficult to enforce consistently across different configurations.
• The start of the Antares year should align with a particular day of the week (e.g., Saturday).
• Users cannot easily predict or control how changes in the configuration will affect the overall date structure.

To address these issues, a new approach is needed that:

• Decouples the date generation from a fixed start date.
• Builds a custom calendar based on the specified parameters that remains consistent regardless of configuration changes.
• Allows for explicit control over the placement of January 1st and the start of the Antares year.
• Maintains correct week numbering and time frequency increments within the custom year structure.
• Provides a predictable and stable date structure that users can rely on when making configuration changes.

Proposed solution:

1. Parameters (Configuration > General):
   Those are the parameters in generaldata (that are renamed for clarity purposes):

   • firstJanuary: The day of the week that January 1st must fall on (e.g., "Monday")
     • (january.1st)
   • firstMonth: The month that starts the Antares year (e.g., "September")
     • (first-month-in-year)
   • firstWeekDay: The day of the week that is considered the start of the week (e.g., "Saturday")
     • (first.weekday)
   • count: Determines the number of dates generated
     • (steps)
   • timeFrequency: Determines the interval between generated dates
     • (level)
   • isLeapYear: Boolean indicating whether the year should be treated as a leap year
     • (leapyear)

2. Antares Year Definition:

   • The Antares year starts with the month specified in firstMonth
   • It lasts for 12 months, ending in the month before the start month of the next year
   • The year is not tied to the calendar year and can span across traditional year boundaries

3. Time Frequency and Count:

   • Annual: 1 date > we display the string "Annual"
   • Monthly: 12 dates > we display a string for each month e.g: "janv.", "fev." etc
   • Weekly: 52 dates (53 if it's a leap year) > we display the weeks number from 1 to 52 or 53 for leap year
   • Daily: 365 dates (366 if it's a leap year ? ) > to be confirmed
   • Hourly: 8760 dates (8784 if it's a leap year ? ) > to be confirmed

4. Leap Year Handling:

   • When isLeapYear is true, the year contains 366 days
   • February has 29 days in a leap year instead of 28

5. Date Generation and Alignment:

   • The system generates dates based on all the parameters
   • Key alignment rule: If January 1st is set to be a Monday, the system back-calculates to ensure that the first day of the Antares year (e.g., September 1st) falls on a Saturday
   • This back-calculation principle applies regardless of the specified firstMonth and firstJanuary

6. Week Start and January 1st Placement:

   • Weeks start on the day specified by firstWeekDay
   • January 1st must fall on the day specified by firstJanuary
   • The system adjusts the calendar to meet both these conditions while maintaining the alignment rule

7. Calendar Construction:

   • Constructs a custom calendar using all parameters
   • Ensures compliance with all rules: Antares year start, January 1st placement, week start, leap year (if applicable), and correct date count for the given frequency
   • Maintains the back-calculation principle to align the start of the Antares year with the specified weekday

Proposed Implementation:

1. Calendar Initialization:
   • Create a base calendar structure starting from a fixed reference year (e.g., 2000, which is a leap year).
   • This base calendar will serve as a template for all calculations, regardless of the actual year being simulated.
2. January 1st Placement:
   • Set January 1st to fall on the specified day of the week (firstJanuary parameter).
   • This becomes the anchor point for all subsequent calculations.
3. Antares Year Start Calculation:
   • From January 1st, move forward to the specified first month of the Antares year (firstMonth parameter).
   • Perform a backward calculation to ensure this date falls on the specified first day of the week (firstWeekDay parameter).
4. Week Numbering Initialization:
   • Start week numbering from this calculated Antares year start.
   • Ensure that week numbers reset appropriately based on the Antares year, not the calendar year.
5. Date Sequence Generation:
   • Generate the sequence of dates based on the time frequency (timeFrequency parameter) and count.
   • For each frequency:
     • annual: Generate "Annual"
     • monthly: Generate monthly dates
     • weekly: Generate weekly dates, maintaining correct week numbers
     • daily: Generate daily dates
     • hourly: Generate hourly timestamps
6. Leap Year Handling:
   • Implement a toggle for leap year calculations (isLeapYear parameter).
   • When enabled, adjust February to have 29 days and modify subsequent calculations accordingly.
7. Formatting and Output:
   • Format each generated date/time point according to the specified frequency.
   • Ensure that formatted output respects the Antares year structure, not the calendar year.
8. Circular Nature Implementation:
   • Design the system to handle the circular nature of the Antares year, where the end of one year seamlessly transitions to the start of the next.
9. Configuration Independence:
   • Ensure that the generated date structure remains consistent and predictable regardless of configuration changes.
   • Implement a system where changing one parameter (e.g. firstMonth) automatically adjusts other parameters to maintain the specified relationships.