pydae 0.57__tar.gz → 0.57.2__tar.gz

{pydae-0.57 → pydae-0.57.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pydae
-Version: 0.57
+Version: 0.57.2
 Summary: =====
 Keywords: engineering
 Author-email: Juan Manuel Mauricio <jmmauricio6@gmail.com>

{pydae-0.57 → pydae-0.57.2}/src/pydae/__init__.py

@@ -7,5 +7,5 @@ Differential Algebraic Equations in Python
 
 """
 
-__version__ = "0.57"
+__version__ = "0.57.2"
  

{pydae-0.57 → pydae-0.57.2}/src/pydae/utils/dates.py

@@ -1,6 +1,6 @@
 import datetime 
 import pytz
-from typing import Optional,List
+from typing import Optional,List,Tuple
 
 def get_absolute_hour_of_year_with_dst(month: int, day: int, day_hour: int, year: int, timezone_name: str) -> int:
     """
@@ -205,20 +205,121 @@ def list_full_hours_between(start_dt: datetime, end_dt: datetime) -> List[dateti
         
     return hours_list
 
-def absolute_hours_list(datetime_list,time_zone='Europe/Paris'):
-
-    result_ini = parse_datetime( '1/12/2024 23:00', 'Europe/Paris')
-    result_end = parse_datetime('31/12/2024 23:00', 'Europe/Paris')
+def absolute_hours_list(date_ini,date_end,time_zone='Europe/Paris'):
 
+    result_ini = parse_datetime(date_ini, time_zone)
+    result_end = parse_datetime(date_end, time_zone)
 
     hours_list = []
     for item in list_full_hours_between(result_ini,result_end):
         hours_list += [datetime_to_hour_of_year(item)]
 
     return hours_list
+
+        
+
+def hour_index_to_date_components(absolute_hour_index: int, timezone_name: str) -> Optional[Tuple[int, int]]:
+    """
+    Converts an absolute hour of the year index (0-indexed) to the corresponding 
+    day of the year and hour of the day, respecting DST rules.
+
+    Args:
+        absolute_hour_index: The 0-indexed hour of the year (e.g., 8759 is the last hour).
+        timezone_name: The IANA time zone string (e.g., 'Europe/Madrid').
+
+    Returns:
+        A tuple (day_of_year, hour_of_day) as integers, or None on error.
+    """
+    
+    current_year = datetime.datetime.now().year # Use the current year for the calculation
+    
+    try:
+        # 1. Define the time zone
+        tz = pytz.timezone(timezone_name)
+
+        # 2. Create the start-of-year time (Jan 1st, 00:00)
+        # This is the reference point for hour index 0.
+        start_of_year_naive = datetime.datetime(current_year, 1, 1, 0, 0, 0)
+        
+        # Localize the start of the year to make it aware
+        start_of_year_aware = tz.localize(start_of_year_naive)
+
+        # 3. Create the time difference
+        # Multiplying the hour index by 3600 gives the exact number of seconds 
+        # that have elapsed since the start_of_year_aware.
+        time_difference = datetime.timedelta(hours=absolute_hour_index)
+
+        # 4. Calculate the target time
+        # This addition operation correctly handles DST shifts. If 25 hours have
+        # passed since Jan 1st, and one hour was lost due to DST, the target time 
+        # will only be advanced by 24 clock hours.
+        target_time_aware = start_of_year_aware + time_difference
+        
+        # 5. Extract the required components
+        # %j gives the 1-indexed day of the year (1-366).
+        day_of_year = int(target_time_aware.strftime('%j'))
+        hour_of_day = target_time_aware.hour # 0-23
+        
+        return (day_of_year, hour_of_day)
+    
+    except pytz.exceptions.UnknownTimeZoneError:
+        print(f"Error: Timezone '{timezone_name}' is not recognized.")
+        return None
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+        return None
+    
+
+def day_to_absolute_hour(day_of_year: int, target_year: int, timezone_name: str = 'Europe/Madrid') -> int:
+    """
+    Calculates the absolute hour of the year (based on UTC) for a specific day 
+    at 00:00 local time, correctly accounting for time zone and DST changes.
+
+    Args:
+        day_of_year: The sequential day of the year (1 for Jan 1st, 365/366 for Dec 31st).
+        target_year: The year for the calculation (e.g., 2024).
+        timezone_name: The target time zone string (e.g., 'Europe/London', 'America/New_York'). 
+                       Defaults to 'UTC'.
+
+    Returns:
+        The total number of hours elapsed from the beginning of the year 
+        (Jan 1st 00:00 UTC) up to the specified date and time (converted to UTC).
+    
+    Raises:
+        pytz.UnknownTimeZoneError: If the provided timezone_name is invalid.
+    """
+    
+    # 1. Define the start of the year and the target date (unlocalized)
+    start_of_year = datetime.datetime(target_year, 1, 1, 0, 0, 0)
+    
+    # Calculate the target date (00:00 local time)
+    # We subtract 1 from day_of_year because Jan 1st is day 1, but represents 0 days of offset.
+    target_date = start_of_year + datetime.timedelta(days=day_of_year - 1)
+
+    try:
+        # 2. Localize the dates
+        tz = pytz.timezone(timezone_name)
         
+        # Localize the date to the target timezone (this handles DST shift at 00:00 if any)
+        # .localize() is the safe way to assign timezone awareness.
+        start_of_year_local = tz.localize(start_of_year)
+        target_date_local = tz.localize(target_date)
+
+        # 3. Convert both localized times to UTC
+        start_of_year_utc = start_of_year_local.astimezone(pytz.utc)
+        target_date_utc = target_date_local.astimezone(pytz.utc)
 
+        # 4. Calculate the difference in hours
+        time_difference = target_date_utc - start_of_year_utc
+        
+        # Convert total seconds in the timedelta to total hours (integer result)
+        absolute_hour = int(time_difference.total_seconds() / 3600)
+        
+        return absolute_hour
 
+    except pytz.UnknownTimeZoneError:
+        raise pytz.UnknownTimeZoneError(f"Time zone '{timezone_name}' is not recognized by pytz.")
+    
 if __name__ == '__main__':
 
     result_1 = parse_datetime('31/12/2024 23:00', 'Europe/Paris')
@@ -229,5 +330,5 @@ if __name__ == '__main__':
 
     print(list_full_hours_between(result_ini,result_end))
 
-    print(absolute_hours_list('1/12/2024 23:00','1/12/2024 23:00'))
+    print(absolute_hours_list('1/1/2024 00:00','31/1/2024 23:00'))