[Policy API] clarify how to meet min for vehicle distribution policies

[jean-populus]

Is your feature request related to a problem? Please describe.

Many cities have a policy for how many vehicles must be distributed in specific geographies at the beginning of the day. This is generally described as the minimum number of vehicles that operator must deploy. To comply with these policies these policies there must be at least that many vehicles at some point during the specified time. This is not usually the way we think of min/max where the min is the floor and the max is the ceiling. In this case the min is a target that the vehicle count needs to hit but doesn't need to be maintained at that level.

Currently there is no way to describe how these distribution vehicle counts have a different compliance measure then regional vehicle mins/caps.

Describe the solution you'd like

Is this a breaking change

• I'm not sure

Impacted Spec

• policy

Describe alternatives you've considered

Additional context

[quicklywilliam]

This is super reminiscent of what we went through with Rates, where we defined Rate Recurrences to accomplish things like a per vehicle fee that gets assessed once a day. During this process, we went through an exercise to take different Policy rules and express them in English to try to find a general form of how you'd "read a rule". What we came up with is:

set the [rule_type] of vehicles in [statuses] to [minimum/maximum/rate_amount] [recurrence][units]

Here are some examples:

• Vehicle cap
  • "set the count of vehicles in any status to maximum 10000 "
• Max parking time
  • "set the time of vehicles in available to maximum 72 hours "
• Speed Limit
  • "set the speed of vehicles in trip to maximum 10 mph "
• Per-trip fee
  • "set the rate of vehicles in trip to 25 rate_amount once"
• Metered parking fee
  • "set the rate of vehicles in [available, unavailable] to 5 rate_amount each_time_unit hours"
• Deployment fee
  • "set the rate of vehicles in service_start to 25 rate_amount each_time_unit days"

So, for this use case, maybe what we are looking for can be accomplished just by allowing recurrences to use for other rule types. For example, the fleet must reach at least 200 once a day:
- "set the count of vehicles in any status to minimum 200 each_time_unit days "

[schnuerle]

Notes from the working group meeting discussions.

• Perhaps introduce concept of recurrence - how often is this measured/applied? Does it only need to meet the condition once?
• Evaluate maximum count over time - was this above the min at any point in time?
• William - Could use rates, but question of is it each time, or for a whole day/hour, etc
• Rate recurrence that could apply to more of the rule types. How often is the rule evaluated?
• Evaluation is checking for compliance
• Once the min is hit, then you know it’s good for that interval
• Jack Reilly Vianova - Max filter over 10 hour enforcement - 5% between 8-12. Look at the previous 4 hours.
• Could look back over a period and find the max, compare to the min, historically look to see if it’s met
• Metrics has min over a time period. Must cross the min once. Metrics could be used.
• What’s the sentence in English for how you define a policy in MDS
• Ride Report offered to share their work on this

@jean-populus and @karcass what do you think of @quicklywilliam's examples to accomplish this by allowing recurrences for other rule types?

William is what you shared here the work you mentioned on the call that Ride Report has done on this?

[jean-populus]

I like idea of [recurrence]. And the options could be once, always, anything else?

[quicklywilliam]

@schnuerle Yes, that is the work I mentioned!

@jean-populus I think that's right, two options but with the ability to specify the time period. And maybe we could have always act as the default? ie:

There must be 200 vehicles minimum (always):
"set the count of vehicles in any status to minimum 200"

There must be 200 vehicles minimum once each day:
"set the count of vehicles in any status to minimum 200 each_time_unit days "

Ideally we'd align with the terms used here with those in rate recurrences, which has each_time_unit but confusingly uses once for recurrences that get evaluated every time. I can't remember if we considered always when we wrote the initial proposal but it strikes me now as a clearer name. So, perhaps we could rename the once option for rate recurrences to always?

Weird side note
I can't really think of a use case here for the per_complete_time_unit recurrence we have for rates. It would be something like "there must be 200 vehicles minimum for a complete hour", totally weird.

[quicklywilliam]

Also, do we have any use cases for this besides count type rules? If not, it seems like it would be very straight forward to make a new count_occurrence field that these options get applied to.

[jean-populus]

Example distribution policy from Baltimore:
Min of 3 vehicles in each Equity Zone by 8 am on each day of service

How this works in real life is that they check to see if the vehicle count reaches 3 at any time between 5am - 9am. Operators comply by looking at the number of vehicles they already have in that area then dropping off more vehicles to reach 3. Operators don't always drop-off 3 vehicles because equity zones are not necessarily high utilization areas so they want to minimize the number of vehicles they have in those zones while still being in compliance. So unfortunately we can't just count vehicle drop-offs.

Example distribution policy from Chicago:
min 25% of scooters in Priority Sub-Area I
min 25% of scooters in Priority Sub-Area 2
at beginning of each day

Example from DDOT:
The dockless vehicle operating company shall balance its fleet of dockless sharing vehicles by having at least six (6) vehicles in each ward by 6:00 a.m. each day.

[jean-populus]

Posting an update from presentation MDS Policy Extensions 15 July 2021

• Another decision of “make Policy more complex” vs. “push the complexity into Metrics and use that.”
• Need some very specific examples
• Proposal: collect examples and revisit

[schnuerle]

Can't recall why I reopened this after Jean closed it. Closing again!