Schedulingvisits¶

flowtask.components.SchedulingVisits ¶

SchedulingVisits ¶

SchedulingVisits(loop=None, job=None, stat=None, **kwargs)

Bases: FlowComponent

Generating the Schedule of Employee Visits with Market Constraints and Visit Cadence.

Overview

The SchedulingVisits class is a Flowtask component for generating a schedule of employee visits based on a set of rules and constraints. This component can be used to optimize the order of visits, minimize travel time, and balance workloads across employees. The schedule is generated by solving a combinatorial optimization problem with support for custom objective functions and constraints.

Example of row consumed:

associate_oid -> object -> G3Q86F5E1JXN1XVM
corporate_email -> object -> buko@trocglobal.com
employee_position -> object -> (3442724.8764311927, -10973885.176252203)
store_id -> object -> BBY0178
store_position -> object -> (3564143.804984759, -10887222.41833608)
market -> object -> Market1
visit_rule -> int64 -> 2
visit_frequency -> object -> Monthly

Example of Row Generated:

Example:

SchedulingVisits:
    use_ghost_employees: true
    ghost_employees: 1
    ghost_employees_column: 'ghost_employees'  # Column name in dataframe for dynamic ghost employees count
    ghost_domain: 'company.com'  # Domain for ghost employee emails
    in_store_percentage: 0.6
    in_store_visit: 0.75
    max_visits_per_day: 4
    max_distance: 120
    year: 2024
    month: 12
    start_hour: 9  # Start working at 9:00 AM
    exception_dates:
    - '2024-12-25'
    exceptions_filename: /home/ubuntu/symbits/Scheduling-Visits-Exceptions.xlsx

Note: - If 'ghost_employees_column' exists in the dataframe, it will use that value for each market - If the column doesn't exist or has null values, it will fall back to the 'ghost_employees' parameter - The 'ghost_domain' parameter allows you to customize the email domain for ghost employees - Ghost employee emails will be generated as: ghost_1@domain, ghost_2@domain, etc. - The 'start_hour' parameter sets when employees begin their workday (default: 9 AM)

When roundtrip=True: - Reduces effective daily capacity (time/distance used for return trips) - More realistic scheduling for depot-based operations - Employees always end day at their starting hub/depot - May increase unscheduled stores due to return trip constraints

When to use roundtrip=True: - Employees must return to central depot/hub - Vehicle check-in/check-out required - Union/labor requirements for end-of-day location - Security/safety requirements

When to use roundtrip=False (default): - Employees can end day anywhere - Maximum coverage/efficiency desired - Field-based operations without central depot

analyze_market_capacity ¶

analyze_market_capacity(df)

Analyze each market's capacity requirements using actual assigned employees.

debug_scheduling_progress ¶

debug_scheduling_progress(schedule_df, exception_df)

Enhanced debug method with duplicate store visit detection.

get_distance ¶

get_distance(coord1, coord2)

Function to calculate distance between two points (latitude, longitude).

get_labor_days ¶

get_labor_days(year=2024, month=9)

Function to get all workdays (Monday to Friday) in a given month.

get_scheduled_dates ¶

get_scheduled_dates(cadence, visit_rule, visit_frequency, workdays, store_index)

Given the visit_rule and visit_frequency, return a list of scheduled dates for the visits.

get_travel_duration ¶

get_travel_duration(origin, destination)

Helper function to get distance and duration between two points.

get_workdays ¶

get_workdays(year, month, exception_dates=None)

Get all workdays (Monday to Friday) in a given month, excluding exception dates.

log_roundtrip_summary ¶

log_roundtrip_summary(schedule_df)

Log summary statistics about roundtrip scheduling.