1from datetime import datetime, timedelta
  2from dateutil.relativedelta import relativedelta
  3from typing import Any, Generator
  4from class_patient import Patient
  5from utils import Utils
  6import pandas as pd
  7from class_hems import HEMS
  8from simpy import FilterStore, Event
  9from numpy.random import SeedSequence
 10
 11import logging
 12from enum import IntEnum
 13
 14class ResourceAllocationReason(IntEnum):
 15    NONE_AVAILABLE = 0
 16    MATCH_PREFERRED_CARE_CAT_HELI = 1
 17    MATCH_PREFERRED_CARE_CAT_CAR = 2
 18    CC_MATCH_EC_HELI = 3
 19    CC_MATCH_EC_CAR = 4
 20    EC_MATCH_CC_HELI = 5
 21    EC_MATCH_CC_CAR = 6
 22    REG_HELI_BENEFIT_MATCH_EC_HELI = 7
 23    REG_HELI_BENEFIT_MATCH_CC_HELI = 8
 24    REG_NO_HELI_BENEFIT_GROUP_AND_VEHICLE = 9
 25    REG_NO_HELI_BENEFIT_GROUP = 10
 26    OTHER_VEHICLE_TYPE = 11
 27    REG_NO_HELI_BENEFIT_ANY = 12
 28    REG_NO_HELI_BENEFIT_VEHICLE = 13
 29
 30class HEMSAvailability():
 31    """
 32        # The HEMS Availability class
 33
 34        This class is a filter store which can provide HEMS resources
 35        based on the time of day and servicing schedule
 36
 37
 38    """
 39
 40    def __init__(self, env, sim_start_date, sim_duration, utility: Utils, servicing_overlap_allowed = False,
 41                 servicing_buffer_weeks = 4, servicing_preferred_month = 1,
 42                 print_debug_messages = False, master_seed=SeedSequence(42)):
 43
 44        self.LOOKUP_LIST = [
 45            "No HEMS resource available", #0
 46            "Preferred HEMS care category and vehicle type match", # 1
 47            "Preferred HEMS care category match but not vehicle type", # 2
 48            "HEMS CC case EC helicopter available", # 3
 49            "HEMS CC case EC car available", # 4
 50            "HEMS EC case CC helicopter available", # 5
 51            "HEMS EC case CC car available", # 6
 52            "HEMS REG helicopter case EC helicopter available",
 53            "HEMS REG helicopter case CC helicopter available",
 54            "HEMS REG case no helicopter benefit preferred group and vehicle type allocated", # 9
 55            "HEMS REG case no helicopter benefit preferred group allocated", # 10
 56            "No HEMS resource available (pref vehicle type = 'Other')", # 11
 57            "HEMS REG case no helicopter benefit first free resource allocated", # 12
 58            "HEMS REG case no helicopter benefit free helicopter allocated" #13
 59        ]
 60
 61        self.env = env
 62        self.print_debug_messages = print_debug_messages
 63        self.master_seed = master_seed
 64        self.utilityClass = utility
 65
 66        # Adding options to set servicing parameters.
 67        self.servicing_overlap_allowed = servicing_overlap_allowed
 68        self.serviing_buffer_weeks = servicing_buffer_weeks
 69        self.servicing_preferred_month = servicing_preferred_month
 70        self.sim_start_date = sim_start_date
 71
 72        self.debug(f"Sim start date {self.sim_start_date}")
 73        # For belts and braces, add an additional year to
 74        # calculate the service schedules since service dates can be walked back to the
 75        # previous year
 76        self.sim_end_date = sim_start_date + timedelta(minutes=sim_duration + (1*365*24*60))
 77
 78        # School holidays
 79        self.school_holidays = pd.read_csv('actual_data/school_holidays.csv')
 80
 81        self.HEMS_resources_list = []
 82
 83        self.active_callsign_groups = set()     # Prevents same crew being used twice...hopefully...
 84        self.active_registrations = set()       # Prevents same vehicle being used twice
 85        self.active_callsigns = set()
 86
 87        # Create a store for HEMS resources
 88        self.store = FilterStore(env)
 89
 90        self.serviceStore = FilterStore(env)
 91
 92        # Prepare HEMS resources for ingesting into store
 93        self.prep_HEMS_resources()
 94
 95        # Populate the store with HEMS resources
 96        self.populate_store()
 97
 98        # Daily servicing check (in case sim starts during a service)
 99        [dow, hod, weekday, month, qtr, current_dt] = self.utilityClass.date_time_of_call(self.sim_start_date, self.env.now)
100
101        self.daily_servicing_check(current_dt, hod, month)
102
103    def debug(self, message: str):
104        if self.print_debug_messages:
105            logging.debug(message)
106            #print(message)
107
108    def daily_servicing_check(self, current_dt: datetime, hour: int, month: int):
109        """
110            Function to iterate through the store and trigger the service check
111            function in the HEMS class
112        """
113        h: HEMS
114
115        self.debug('------ DAILY SERVICING CHECK -------')
116
117        GDAAS_service = False
118
119        all_resources = self.serviceStore.items + self.store.items
120        for h in all_resources:
121            if h.registration == 'g-daas':
122                GDAAS_service = h.unavailable_due_to_service(current_dt)
123                break
124
125        self.debug(f"GDAAS_service is {GDAAS_service}")
126
127        # --- Return from serviceStore to store ---
128        to_return = [
129            (s.category, s.registration)
130            for s in self.serviceStore.items
131            if not s.service_check(current_dt, GDAAS_service) # Note the NOT here!
132        ]
133
134        # Attempted fix for gap after return from H70 duties
135        for h in self.store.items:
136            if h.registration == 'g-daan' and not GDAAS_service:
137                h.callsign_group = 71
138                h.callsign = 'H71'
139
140        if to_return:
141            self.debug("Service store has items to return")
142
143        for category, registration in to_return:
144            s = yield self.serviceStore.get(
145                lambda item: item.category == category and item.registration == registration
146            )
147            yield self.store.put(s)
148            self.debug(f"Returned [{s.category} / {s.registration}] from service to store")
149
150        # --- Send from store to serviceStore ---
151        to_service = [
152            (h.category, h.registration)
153            for h in self.store.items
154            if h.service_check(current_dt, GDAAS_service)
155        ]
156
157        for category, registration in to_service:
158            self.debug("****************")
159            self.debug(f"HEMS [{category} / {registration}] being serviced, removing from store")
160
161            h = yield self.store.get(
162                lambda item: item.category == category and item.registration == registration
163            )
164
165            self.debug(f"HEMS [{h.category} / {h.registration}] successfully removed from store")
166            yield self.serviceStore.put(h)
167            self.debug(f"HEMS [{h.category} / {h.registration}] moved to service store")
168            self.debug("***********")
169
170        self.debug(self.current_store_status(hour, month))
171        self.debug(self.current_store_status(hour, month, 'service'))
172
173        [dow, hod, weekday, month, qtr, current_dt] = self.utilityClass.date_time_of_call(self.sim_start_date, self.env.now)
174        for h in self.store.items:
175            if h.registration == 'g-daan':
176                self.debug(f"[{self.env.now}] g-daan status: in_use={h.in_use}, callsign={h.callsign}, group={h.callsign_group}, on_shift={h.hems_resource_on_shift(hod, month)}")
177
178        self.debug('------ END OF DAILY SERVICING CHECK -------')
179
180
181    def prep_HEMS_resources(self) -> None:
182        """
183            This function ingests HEMS resource data from a user-supplied CSV file
184            and populates a list of HEMS class objects. The key activity here is
185            the calculation of service schedules for each HEMS object, taking into account a
186            user-specified preferred month of servicing, service duration, and a buffer period
187            following a service to allow for over-runs and school holidays
188
189        """
190
191        schedule = []
192        service_dates = []
193
194
195        # Calculate service schedules for each resource
196
197        SERVICING_SCHEDULE = pd.read_csv('actual_data/service_schedules_by_model.csv')
198        SERVICE_HISTORY = pd.read_csv('actual_data/service_history.csv', na_values=0)
199        CALLSIGN_REGISTRATION = pd.read_csv('actual_data/callsign_registration_lookup.csv')
200
201        SERVICING_SCHEDULE = SERVICING_SCHEDULE.merge(
202            CALLSIGN_REGISTRATION,
203            how="right",
204            on="model"
205            )
206
207        SERVICING_SCHEDULE = SERVICING_SCHEDULE.merge(
208            SERVICE_HISTORY,
209            how="left",
210            on="registration"
211            )
212
213        self.debug(f"prep_hems_resources: schedule {SERVICING_SCHEDULE}")
214
215        for index, row in SERVICING_SCHEDULE.iterrows():
216            #self.debug(row)
217            current_resource_service_dates = []
218            # Check if service date provided
219            if not pd.isna(row['last_service']):
220                #self.debug(f"Checking {row['registration']} with previous service date of {row['last_service']}")
221                last_service = datetime.strptime(row['last_service'], "%Y-%m-%d")
222                service_date = last_service
223
224                while last_service < self.sim_end_date:
225
226                    end_date = last_service + \
227                        timedelta(weeks = int(row['service_duration_weeks'])) + \
228                        timedelta(weeks=self.serviing_buffer_weeks)
229
230                    service_date, end_date = self.find_next_service_date(
231                        last_service,
232                        row["service_schedule_months"],
233                        service_dates,
234                        row['service_duration_weeks']
235                    )
236
237                    schedule.append((row['registration'], service_date, end_date))
238                    #self.debug(service_date)
239                    service_dates.append({'service_start_date': service_date, 'service_end_date': end_date})
240
241                    current_resource_service_dates.append({'service_start_date': service_date, 'service_end_date': end_date})
242                    #self.debug(service_dates)
243                    #self.debug(current_resource_service_dates)
244                    last_service = service_date
245            else:
246                schedule.append((row['registration'], None, None))
247                #self.debug(schedule)
248
249            service_df = pd.DataFrame(schedule, columns=["registration", "service_start_date", "service_end_date"])
250
251            service_df.to_csv("data/service_dates.csv", index=False)
252
253        # Append those to the HEMS resource.
254
255        HEMS_RESOURCES = (
256            pd.read_csv("actual_data/HEMS_ROTA.csv")
257                # Add model and servicing rules
258                .merge(
259                    SERVICING_SCHEDULE,
260                    on=["callsign", "vehicle_type"],
261                    how="left"
262                )
263        )
264
265        for index, row in HEMS_RESOURCES.iterrows():
266
267            s = service_df[service_df['registration'] == row['registration']]
268            #self.debug(s)
269
270            # Create new HEMS resource and add to HEMS_resource_list
271            #pd.DataFrame(columns=['year', 'service_start_date', 'service_end_date'])
272            hems = HEMS(
273                callsign            = row['callsign'],
274                callsign_group      = row['callsign_group'],
275                vehicle_type        = row['vehicle_type'],
276                category            = row['category'],
277                registration        = row['registration'],
278                summer_start        = row['summer_start'],
279                winter_start        = row['winter_start'],
280                summer_end          = row['summer_end'],
281                winter_end          = row['winter_end'],
282                servicing_schedule  = s,
283                resource_id         = row['registration']
284            )
285
286            self.HEMS_resources_list.append(hems)
287
288        #self.debug(self.HEMS_resources_list)
289
290
291    def populate_store(self):
292        """
293            Function to populate the filestore with HEMS class objects
294            contained in a class list
295        """
296
297        h: HEMS
298        for h in self.HEMS_resources_list:
299            self.debug(f"Populating resource store: HEMS({h.callsign})")
300            self.debug(h.servicing_schedule)
301            self.store.put(h)
302
303
304    def add_hems(self):
305        """
306            Future function to allow for adding HEMS resources.
307            We might not use this (we could just amend the HEMS_ROTA dataframe, for example)
308            but might be useful for 'what if' simulations
309        """
310        pass
311
312    # def resource_allocation_lookup(self, prefered_lookup: int):
313    #     """
314    #         Function to return description of lookup allocation choice
315
316    #     """
317
318    #     lookup_list = [
319    #         "No HEMS resource available",
320    #         "Preferred HEMS care category and vehicle type match",
321    #         "Preferred HEMS care category match but not vehicle type",
322    #         "HEMS CC case EC helicopter available",
323    #         "HEMS CC case EC car available",
324    #         "HEMS EC case CC helicopter available",
325    #         "HEMS EC case CC car available",
326    #         "HEMS helicopter case EC helicopter available",
327    #         "HEMS helicopter case CC helicopter available",
328    #         "HEMS REG case no helicopter benefit preferred group and vehicle type allocated",
329	#         "HEMS REG case no helicopter benefit preferred group allocated",
330    #         "No HEMS resource available (pref vehicle type = 'Other')",
331    #         "HEMS REG case no helicopter benefit first free resource allocated"
332    #     ]
333
334    #     return lookup_list[prefered_lookup]
335
336    def resource_allocation_lookup(self, reason: ResourceAllocationReason) -> str:
337        return self.LOOKUP_LIST[reason.value]
338
339    def current_store_status(self, hour, month, store = 'resource') -> list[str]:
340            """
341                Debugging function to return current state of store
342            """
343
344            current_store_items = []
345
346            h: HEMS
347
348            if store == 'resource':
349                for h in self.store.items:
350                    current_store_items.append(f"{h.callsign} ({h.category} online: {h.hems_resource_on_shift(hour, month)} {h.registration})")
351            else:
352                for h in self.serviceStore.items:
353                    current_store_items.append(f"{h.callsign} ({h.category} online: {h.hems_resource_on_shift(hour, month)} {h.registration})")
354
355            return current_store_items
356
357
358    # def preferred_resource_available(self, pt: Patient) -> list[HEMS | None, str]:
359
360    #     """
361    #         Check whether the preferred resource group is available. Returns a list with either the HEMS resource or None, and
362    #         an indication as to whether the resource was available, or another resource in an established hierachy of
363    #         availability can be allocated
364    #     """
365
366    #     # Initialise object HEMS as a placeholder object
367    #     hems: HEMS | None = None
368    #     # Initialise variable 'preferred' to False
369    #     preferred = 999 # This will be used to ensure that the most desireable resource
370    #                 # is allocated given that multiple matches may be found
371    #     preferred_lookup = 0 # This will be used to code the resource allocation choice
372
373    #     preferred_care_category = pt.hems_cc_or_ec
374
375    #     self.debug(f"EC/CC resource with {preferred_care_category} and hour {pt.hour} and qtr {pt.qtr}")
376
377    #     h: HEMS
378    #     for h in self.store.items:
379
380    #         # There is a hierachy of calls:
381    #         # CC = H70 helicopter then car, then H71 helicopter then car then CC72
382    #         # EC = H71 helicopter then car, then CC72, then H70 helicopter then car
383    #         # If no resources then return None
384
385    #         if not h.in_use and h.hems_resource_on_shift(pt.hour, pt.qtr):
386    #             # self.debug(f"Checking whether to generate ad-hoc reason for {h} ({h.vehicle_type} - {h.callsign_group})")
387
388    #             if ( # Skip this resource if any of the following are true:
389    #                 h.in_use or
390    #                 h.being_serviced or
391    #                 not h.hems_resource_on_shift(pt.hour, pt.qtr) or
392    #                 # Skip if crew is already in use
393    #                 h.callsign_group in self.active_callsign_groups or
394    #                 h.registration in self.active_registrations
395    #             ):
396    #                 # self.debug(f"Skipping ad-hoc unavailability check for {h}")
397    #                 continue
398
399    #             if h.vehicle_type == "car":
400    #                 ad_hoc_reason = "available"
401    #             else:
402    #                 ad_hoc_reason = self.utilityClass.sample_ad_hoc_reason(pt.hour, pt.qtr, h.registration)
403
404    #             self.debug(f"({h.callsign}) Sampled reason for patient {pt.id} ({pt.hems_cc_or_ec}) is: {ad_hoc_reason}")
405
406    #             if ad_hoc_reason != "available":
407    #                 continue
408
409    #             if h.category == preferred_care_category and h.vehicle_type == "helicopter" and not h.being_serviced:
410    #                 hems = h
411    #                 preferred = 1 # Top choice
412    #                 preferred_lookup = 1
413    #                 return [hems,  self.resource_allocation_lookup(preferred_lookup)]
414
415    #             elif h.category == preferred_care_category and not h.being_serviced:
416    #                 hems = h
417    #                 preferred = 2 # Second choice (correct care category, but not vehicle type)
418    #                 preferred_lookup = 2
419
420    #             elif preferred_care_category == 'CC':
421    #                 if h.vehicle_type == 'helicopter' and h.category == 'EC' and not h.being_serviced:
422    #                     if preferred > 3:
423    #                         hems = h
424    #                         preferred = 3 # Third  choice (EC helicopter)
425    #                         preferred_lookup = 3
426
427    #                 elif h.category == 'EC' and not h.being_serviced:
428    #                     if preferred > 4:
429    #                         hems = h
430    #                         preferred = 4
431    #                         preferred_lookup = 4
432
433    #             elif preferred_care_category == 'EC':
434    #                 if h.vehicle_type == 'helicopter' and h.category == 'CC' and not h.being_serviced:
435    #                     if preferred > 3:
436    #                         hems = h
437    #                         preferred = 3 # CC helicopter available
438    #                         preferred_lookup = 5
439
440    #                 elif h.category == 'CC' and not h.being_serviced:
441    #                     hems = h
442    #                     preferred = 4
443    #                     preferred_lookup = 6
444
445    #     self.debug(f"preferred lookup {preferred_lookup} and preferred = {preferred}")
446
447    #     if preferred_lookup != 999:
448    #         return [hems, self.resource_allocation_lookup(preferred_lookup)]
449    #     else:
450    #         return [None, self.resource_allocation_lookup(0)]
451
452    def preferred_resource_available(self, pt: Patient) -> list[HEMS | None, str]:
453        """
454        Determine the best available HEMS resource for an EC/CC case based on the
455        patient's preferred care category (EC = Enhanced Care, CC = Critical Care),
456        vehicle type, and ad-hoc availability. Returns the chosen HEMS unit and
457        the reason for its selection.
458
459        Returns:
460            A list containing:
461                - The selected HEMS unit (or None if none available)
462                - A lookup code describing the allocation reason
463        """
464        # Retrieve patient’s preferred care category
465        preferred_category = pt.hems_cc_or_ec
466        self.debug(f"EC/CC resource with {preferred_category} and hour {pt.hour} and qtr {pt.qtr}")
467
468        best_hems: HEMS | None = None       # Best-matching HEMS unit found so far
469        best_priority = float('inf')        # Lower values = better matches
470        best_lookup = ResourceAllocationReason.NONE_AVAILABLE # Reason for final allocation
471
472        for h in self.store.items:
473            # --- FILTER OUT UNAVAILABLE RESOURCES ---
474            if (
475                h.in_use or  # Already dispatched
476                h.being_serviced or # Currently under maintenance
477                not h.hems_resource_on_shift(pt.hour, pt.month) or # Not scheduled for shift now
478                h.callsign_group in self.active_callsign_groups or # Another unit from this group is active (so crew is engaged elsewhere)
479                h.registration in self.active_registrations # This specific unit is already dispatched
480            ):
481                continue  # Move to the next HEMS unit
482
483            # Check ad-hoc reason
484            # For "car" units, assume always available.
485            # For helicopters, simulate availability using ad-hoc logic (e.g., weather, servicing).
486            reason = "available" if h.vehicle_type == "car" else self.utilityClass.sample_ad_hoc_reason(pt.hour, pt.qtr, h.registration)
487            self.debug(f"({h.callsign}) Sampled reason for patient {pt.id} ({pt.hems_cc_or_ec}) is: {reason}")
488
489            if reason != "available":
490                continue # Skip this unit if not usable
491
492            # Decide priority and reason
493            priority = None
494            lookup = None
495
496            # 1. Best case: resource category matches preferred care category *and* is a helicopter
497            if h.category == preferred_category and h.vehicle_type == "helicopter":
498                priority = 1
499                lookup = ResourceAllocationReason.MATCH_PREFERRED_CARE_CAT_HELI
500
501            # 2. Next best: resource category matches preferred care category, but is a car
502            elif h.category == preferred_category:
503                priority = 2
504                lookup = ResourceAllocationReason.MATCH_PREFERRED_CARE_CAT_CAR
505
506            # 3–4. Category mismatch fallback options:
507            # For a CC preference, fall back to EC providers if needed
508            elif preferred_category == "CC":
509                if h.category == "EC" and h.vehicle_type == "helicopter":
510                    priority = 3
511                    lookup = ResourceAllocationReason.CC_MATCH_EC_HELI
512                elif h.category == "EC":
513                    priority = 4
514                    lookup = ResourceAllocationReason.CC_MATCH_EC_CAR
515
516            # For an EC preference, fall back to CC providers if needed
517            elif preferred_category == "EC":
518                if h.category == "CC" and h.vehicle_type == "helicopter":
519                    priority = 3
520                    lookup = ResourceAllocationReason.EC_MATCH_CC_HELI
521                elif h.category == "CC":
522                    priority = 4
523                    lookup = ResourceAllocationReason.EC_MATCH_CC_CAR
524
525            # --- CHECK IF THIS IS THE BEST OPTION SO FAR ---
526            if priority is not None and priority < best_priority:
527                best_hems = h
528                best_priority = priority
529                best_lookup = lookup
530
531                # Immediate return if best possible match found (priority 1)
532                if priority == 1:
533                    self.debug(f"Top priority match found: {best_lookup.name} ({best_lookup.value})")
534                    return [best_hems, self.resource_allocation_lookup(best_lookup)]
535
536        # Final fallback: return the best match found (if any), or none with reason
537        self.debug(f"Selected best lookup: {best_lookup.name} ({best_lookup.value}) with priority = {best_priority}")
538        return [best_hems, self.resource_allocation_lookup(best_lookup)]
539
540
541    def allocate_resource(self, pt: Patient) -> Any | Event:
542        """
543        Attempt to allocate a resource from the preferred group.
544        """
545        resource_event: Event = self.env.event()
546
547        def process() -> Generator[Any, Any, None]:
548            self.debug(f"Allocating resource for {pt.id} and care cat {pt.hems_cc_or_ec}")
549
550            pref_res: list[HEMS | None, str] = self.preferred_resource_available(pt)
551
552            if pref_res[0] is None:
553                return resource_event.succeed([None, pref_res[1], None])
554
555            primary = pref_res[0]
556
557            # Block if in-use by callsign group, registration, or callsign
558            if primary.callsign_group in self.active_callsign_groups:
559                self.debug(f"[BLOCKED] Callsign group {primary.callsign_group} in use")
560                return resource_event.succeed([None, pref_res[1], None])
561
562            if primary.registration in self.active_registrations:
563                self.debug(f"[BLOCKED] Registration {primary.registration} in use")
564                return resource_event.succeed([None, pref_res[1], None])
565
566            if primary.callsign in self.active_callsigns:
567                self.debug(f"[BLOCKED] Callsign {primary.callsign} already in use")
568                return resource_event.succeed([None, pref_res[1], None])
569
570            self.active_callsign_groups.add(primary.callsign_group)
571            self.active_registrations.add(primary.registration)
572            self.active_callsigns.add(primary.callsign)
573
574            with self.store.get(lambda r: r == primary) as primary_request:
575                result = yield primary_request | self.env.timeout(0.1)
576
577                if primary_request in result:
578                    primary.in_use = True
579                    pt.hems_callsign_group = primary.callsign_group
580                    pt.hems_vehicle_type = primary.vehicle_type
581                    pt.hems_category = primary.category
582
583                    # self.active_callsign_groups.add(primary.callsign_group)
584                    # self.active_registrations.add(primary.registration)
585                    # self.active_callsigns.add(primary.callsign)
586
587                    # Try to get a secondary resource
588                    with self.store.get(lambda r:
589                        r != primary and
590                        r.callsign_group == pt.hems_callsign_group and
591                        r.category == pt.hems_category and
592                        r.hems_resource_on_shift(pt.hour, pt.month) and
593                        r.callsign_group not in self.active_callsign_groups and
594                        r.registration not in self.active_registrations and
595                        r.callsign not in self.active_callsigns
596                    ) as secondary_request:
597
598                        result2 = yield secondary_request | self.env.timeout(0.1)
599                        secondary = None
600
601                        if secondary_request in result2:
602                            secondary = result2[secondary_request]
603                            secondary.in_use = True
604                            self.active_callsign_groups.add(secondary.callsign_group)
605                            self.active_registrations.add(secondary.registration)
606                            self.active_callsigns.add(secondary.callsign)
607
608                    return resource_event.succeed([primary, pref_res[1], secondary])
609                else:
610                        # Roll back if unsuccessful
611                    self.active_callsign_groups.discard(primary.callsign_group)
612                    self.active_registrations.discard(primary.registration)
613                    self.active_callsigns.discard(primary.callsign)
614
615                    return resource_event.succeed([None, pref_res[1], None])
616
617        self.env.process(process())
618        return resource_event
619
620
621    def return_resource(self, resource: HEMS, secondary_resource: HEMS|None) -> None:
622        """
623            Class to return HEMS class object back to the filestore.
624        """
625
626        resource.in_use = False
627        self.active_callsign_groups.discard(resource.callsign_group)
628        self.active_registrations.discard(resource.registration)
629        self.active_callsigns.discard(resource.callsign)
630        self.store.put(resource)
631        self.debug(f"{resource.callsign} finished job")
632
633        if secondary_resource is not None:
634            secondary_resource.in_use = False
635            self.active_callsign_groups.discard(secondary_resource.callsign_group)
636            self.active_registrations.discard(secondary_resource.registration)
637            self.active_callsigns.discard(secondary_resource.callsign)
638            self.store.put(secondary_resource)
639            self.debug(f"{secondary_resource.callsign} free as {resource.callsign} finished job")
640
641
642
643    def years_between(self, start_date: datetime, end_date: datetime) -> list[int]:
644        """
645            Function to return a list of years between given start and end date
646        """
647        return list(range(start_date.year, end_date.year + 1))
648
649
650    def do_ranges_overlap(self, start1: datetime, end1: datetime, start2: datetime, end2: datetime) -> bool:
651        """
652            Function to determine whether two sets of datetimes overlap
653        """
654        return max(start1, start2) <= min(end1, end2)
655
656
657    def is_during_school_holidays(self, start_date: datetime, end_date: datetime) -> bool:
658        """
659            Function to calculate whether given start and end date time period falls within
660            a school holiday
661        """
662
663        for index, row in self.school_holidays.iterrows():
664
665            if self.do_ranges_overlap(pd.to_datetime(row['start_date']), pd.to_datetime(row['end_date']), start_date, end_date):
666                return True
667
668        return False
669
670
671    def is_other_resource_being_serviced(self, start_date, end_date, service_dates):
672        """
673            Function to determine whether any resource is being services between a
674            given start and end date period.
675        """
676
677        for sd in service_dates:
678            if self.do_ranges_overlap(sd['service_start_date'], sd['service_end_date'], start_date, end_date):
679                return True
680
681        return False
682
683
684    def find_next_service_date(self, last_service_date: datetime, interval_months: int, service_dates: list, service_duration: int) -> list[datetime]:
685        """
686            Function to determine the next service date for a resource. The date is determine by
687            the servicing schedule for the resource, the preferred month of servicing, and to
688            avoid dates that fall in either school holidays or when other resources are being serviced.
689        """
690
691        next_due_date = last_service_date + relativedelta(months = interval_months) # Approximate month length
692        end_date = next_due_date + timedelta(weeks = service_duration)
693
694        preferred_date = datetime(next_due_date.year, self.servicing_preferred_month , 2)
695        preferred_end_date = preferred_date + timedelta(weeks = service_duration)
696
697        if next_due_date.month > preferred_date.month:
698            preferred_date += relativedelta(years = 1)
699
700        # self.debug(f"Next due: {next_due_date} with end date {end_date} and preferred_date is {preferred_date} with pref end {preferred_end_date}")
701
702        # If preferred date is valid, use it
703        if preferred_date <= next_due_date and not self.is_during_school_holidays(preferred_date, preferred_end_date):
704            next_due_date = preferred_date
705
706        while True:
707            if self.is_during_school_holidays(next_due_date, end_date) or self.is_other_resource_being_serviced(next_due_date, end_date, service_dates):
708                next_due_date -= timedelta(days = 1)
709                end_date = next_due_date + timedelta(weeks = service_duration)
710                continue
711            else:
712                break
713
714        return [next_due_date, end_date]
715
716
717    # def preferred_regular_group_available(self, pt: Patient) -> list[HEMS | None, str]:
718    #     """
719    #     Check availability for REG jobs while avoiding assigning two units from
720    #     the same crew/callsign group.
721    #     """
722    #     hems: HEMS | None = None
723    #     preferred = 999
724    #     preferred_lookup = 0
725
726    #     preferred_group = pt.hems_pref_callsign_group
727    #     preferred_vehicle_type = pt.hems_pref_vehicle_type
728    #     helicopter_benefit = pt.hems_helicopter_benefit
729
730    #     for h in self.store.items:
731
732    #         if (
733    #             h.in_use or
734    #             h.being_serviced or
735    #             not h.hems_resource_on_shift(pt.hour, pt.qtr) or
736    #             # Skip if crew is already in use
737    #             h.callsign_group in self.active_callsign_groups or
738    #             h.registration in self.active_registrations
739    #             ):
740    #             continue
741
742
743    #         if h.vehicle_type == "car":
744    #             ad_hoc_reason = "available"
745    #         else:
746    #             ad_hoc_reason = self.utilityClass.sample_ad_hoc_reason(pt.hour, pt.qtr, h.registration)
747
748    #         self.debug(f"({h.callsign}) Sampled reason for patient {pt.id} (REG) is: {ad_hoc_reason}")
749
750    #         if ad_hoc_reason != "available":
751    #             continue
752
753    #         # Helicopter benefit cases
754    #         if helicopter_benefit == 'y':
755    #             if h.vehicle_type == 'helicopter' and h.category == 'EC':
756    #                 hems = h
757    #                 preferred_lookup = 7
758    #                 break
759    #             elif h.vehicle_type == 'helicopter':
760    #                 if preferred > 2:
761    #                     hems = h
762    #                     preferred = 2
763    #                     preferred_lookup = 8
764
765    #         # Regular (non-helicopter) cases
766    #         else:
767    #             if (h.callsign_group == preferred_group
768    #                 and h.vehicle_type == preferred_vehicle_type):
769    #                 hems = h
770    #                 preferred_lookup = 9
771    #                 break
772    #             elif h.callsign_group == preferred_group:
773    #                 if preferred > 4:
774    #                     hems = h
775    #                     preferred = 4
776    #                     preferred_lookup = 10
777    #             else:
778    #                 if preferred > 5:
779    #                     hems = h
780    #                     preferred = 5
781    #                     preferred_lookup = 12
782
783    #     return [hems, self.resource_allocation_lookup(preferred_lookup if hems else 0)]
784
785    def preferred_regular_group_available(self, pt: Patient) -> list[HEMS | None, str]:
786        """
787        Determine the most suitable HEMS (Helicopter Emergency Medical Service) unit
788        for a REG (regular) job, ensuring that two units from the same crew/callsign
789        group are not simultaneously active. This method prioritizes matching the
790        patient's preferences and helicopter benefit where applicable.
791
792        Returns:
793            A list containing:
794                - The selected HEMS unit (or None if none available)
795                - A lookup code describing the allocation reason
796        """
797        # Initialize selection variables
798        hems: HEMS | None = None # The selected resource
799        preferred = float("inf") # Lower numbers mean more preferred options (2, 4, 5 are used below)
800        preferred_lookup = ResourceAllocationReason.NONE_AVAILABLE  # Reason code for selection
801
802        preferred_group = pt.hems_pref_callsign_group        # Preferred crew group
803        preferred_vehicle_type = pt.hems_pref_vehicle_type    # e.g., "car" or "helicopter"
804        helicopter_benefit = pt.hems_helicopter_benefit       # "y" if helicopter has clinical benefit
805        # Iterate through all HEMS resources stored
806        for h in self.store.items:
807            if (
808                h.in_use or # Already dispatched
809                h.being_serviced or # Currently under maintenance
810                not h.hems_resource_on_shift(pt.hour, pt.month) or # Not scheduled for shift now
811                h.callsign_group in self.active_callsign_groups or  # Another unit from this group is active (so crew is engaged elsewhere)
812                h.registration in self.active_registrations # This specific unit is already dispatched
813            ):
814                continue # Move to the next HEMS unit
815
816            # Check ad hoc availability
817            # For "car" units, assume always available.
818            # For helicopters, simulate availability using ad-hoc logic (e.g., weather, servicing).
819            reason = "available" if h.vehicle_type == "car" else self.utilityClass.sample_ad_hoc_reason(pt.hour, pt.qtr, h.registration)
820            self.debug(f"({h.callsign}) Sampled reason for patient {pt.id} (REG) is: {reason}")
821
822            if reason != "available":
823                continue # Skip this unit if not usable
824
825            # --- HELICOPTER BENEFIT CASE ---
826            # P3 = Helicopter patient
827            # Resources allocated in following order:
828            # IF H70 available = SEND
829            # ELSE H71 available = SEND
830
831            # Assume 30% chance of knowing in advance that it's going to be a heli benefit case
832            # when choosing to send a resource (and if you know that, don't fall back to
833            # sending a car)
834            if helicopter_benefit == "y" and self.utilityClass.rngs["know_heli_benefit"].uniform(0, 1) <= 0.5:
835                # Priority 1: CC-category helicopter (assumed most beneficial)
836                    if h.vehicle_type == "helicopter" and h.category == "CC":
837                        hems = h
838                        preferred_lookup = ResourceAllocationReason.REG_HELI_BENEFIT_MATCH_CC_HELI
839                        break
840                    # Priority 2: Any helicopter (less preferred than CC, hence priority = 2)
841                    elif h.vehicle_type == "helicopter" and preferred > 2:
842                        hems = h
843                        preferred = 2
844                        preferred_lookup = ResourceAllocationReason.REG_HELI_BENEFIT_MATCH_EC_HELI
845
846
847                # If no EC or CC helicopters are available, then:
848                # - hems remains None
849                # - preferred_lookup remains at its initial value (ResourceAllocationReason.NONE_AVAILABLE)
850                # - The function exits the loop without assigning a resource.
851
852            # --- REGULAR JOB WITH NO SIMULATED HELICOPTER BENEFIT ---
853            else:
854                # Best match: matching both preferred callsign group and vehicle type
855                if h.callsign_group == preferred_group and h.vehicle_type == preferred_vehicle_type:
856                    hems = h
857                    preferred_lookup = ResourceAllocationReason.REG_NO_HELI_BENEFIT_GROUP_AND_VEHICLE
858                    break
859                # Next best: send a helicopter
860                elif h.vehicle_type == "helicopter" and preferred > 3:
861                    hems = h
862                    preferred = 3
863                    preferred_lookup = ResourceAllocationReason.REG_NO_HELI_BENEFIT_VEHICLE
864                # Next best: match only on preferred callsign group
865                elif h.callsign_group == preferred_group and preferred > 4:
866                    hems = h
867                    preferred = 4
868                    preferred_lookup = ResourceAllocationReason.REG_NO_HELI_BENEFIT_GROUP
869                # Fallback: any available resource
870                elif preferred > 5:
871                    hems = h
872                    preferred = 5
873                    preferred_lookup = ResourceAllocationReason.REG_NO_HELI_BENEFIT_ANY
874
875        # Return the best found HEMS resource and reason for selection
876        self.debug(f"Selected REG (heli benefit = {helicopter_benefit}) lookup: {preferred_lookup.name} ({preferred_lookup.value})")
877        return [hems, self.resource_allocation_lookup(preferred_lookup if hems else ResourceAllocationReason.NONE_AVAILABLE)]
878
879
880    def allocate_regular_resource(self, pt: Patient) -> Any | Event:
881        """
882        Attempt to allocate a resource from the preferred group (REG jobs).
883        """
884        resource_event: Event = self.env.event()
885
886        def process() -> Generator[Any, Any, None]:
887            # if pt.hems_pref_vehicle_type == "Other":
888            #     pref_res = [None, self.resource_allocation_lookup(11)]
889            # else:
890            pref_res = self.preferred_regular_group_available(pt)
891
892            if pref_res[0] is None:
893                return resource_event.succeed([None, pref_res[1], None])
894
895            primary = pref_res[0]
896
897            # Block if in-use by callsign group, registration, or callsign
898            if primary.callsign_group in self.active_callsign_groups:
899                self.debug(f"[BLOCKED] Regular Callsign group {primary.callsign_group} in use")
900                return resource_event.succeed([None, pref_res[1], None])
901
902            if primary.registration in self.active_registrations:
903                self.debug(f"[BLOCKED] Regular Registration {primary.registration} in use")
904                return resource_event.succeed([None, pref_res[1], None])
905
906            if primary.callsign in self.active_callsigns:
907                self.debug(f"[BLOCKED] Regular Callsign {primary.callsign} already in use")
908                return resource_event.succeed([None, pref_res[1], None])
909
910            self.active_callsign_groups.add(primary.callsign_group)
911            self.active_registrations.add(primary.registration)
912            self.active_callsigns.add(primary.callsign)
913
914            with self.store.get(lambda r: r == primary) as primary_request:
915                result = yield primary_request | self.env.timeout(0.1)
916
917                if primary_request in result:
918                    primary.in_use = True
919                    pt.hems_callsign_group = primary.callsign_group
920                    pt.hems_vehicle_type = primary.vehicle_type
921                    pt.hems_category = primary.category
922
923                    # self.active_callsign_groups.add(primary.callsign_group)
924                    # self.active_registrations.add(primary.registration)
925                    # self.active_callsigns.add(primary.callsign)
926
927                    # Try to get a secondary resource
928                    with self.store.get(lambda r:
929                        r != primary and
930                        r.callsign_group == pt.hems_callsign_group and
931                        r.category == pt.hems_category and
932                        r.hems_resource_on_shift(pt.hour, pt.month) and
933                        r.callsign_group not in self.active_callsign_groups and
934                        r.registration not in self.active_registrations and
935                        r.callsign not in self.active_callsigns
936                    ) as secondary_request:
937
938                        result2 = yield secondary_request | self.env.timeout(0.1)
939                        secondary = None
940
941                        if secondary_request in result2:
942                            secondary = result2[secondary_request]
943                            secondary.in_use = True
944                            self.active_callsign_groups.add(secondary.callsign_group)
945                            self.active_registrations.add(secondary.registration)
946                            self.active_callsigns.add(secondary.callsign)
947
948                    return resource_event.succeed([primary, pref_res[1], secondary])
949
950                else:
951                    # Roll back if unsuccessful
952                    self.active_callsign_groups.discard(primary.callsign_group)
953                    self.active_registrations.discard(primary.registration)
954                    self.active_callsigns.discard(primary.callsign)
955
956                    return resource_event.succeed([None, pref_res[1], None])
957
958        self.env.process(process())
959        return resource_event