Calculated Proximity Adjustments / Custom Best-Hold Selection Sort Order

[Lebbeous Fogle-Weekley]

For Evergreen master/2.4+

    Calculated Proximity Adjustments, a new feature

    Allows customization to the way that Evergreen measures the distance
    between org units for the purposes of 1) determining what copy at what
    org unit is best suited for targeting a title-level hold, and 2)
    determining what hold is best suited for fulfillment by a copy-in-hand
    at capture (checkin) time. The customization is based on a table
    'actor.org_unit_proximity_adjustment', with certain matching criteria
    that the system compares to properties of the holds and copies in
    question.

    This feature is actually side-ported from the FulfILLment project, where
    it was originally developed by Mike Rylander. Lebbeous Fogle-Weekley
    was responsible for integration into current Evergreen code, some
    testing and bug-fixing, and minor refinement of documentation.

Note to testers: 1) see tech specs included in the branch, 2) the first place to see results of these adjustments is in action.hold_copy_map right after a hold is targeted. Behavior of the system (which copies show up on pull lists, which hold is selected next for a copy when the copy is checked in later) follows suit.

Thanks to Bibliomation, MassLNC, HSLC and Sage for sponsoring this work!

http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/senator/hold-prox-newsquash

[Thomas Berezansky (tsbere)]

At this point I question something:

How can we pre-calc this proximity on the copy when we don't know *where* the copy will be captured? Not to mention we could have issues with not taking into account where we currently are holding the copy.

It isn't like we know the copy will be captured at the owning library, after all. (Though I could see FulfILLment being able to make that assumption)

[Mike Rylander (mrylander)]

There are several ways one might design proximity-adjusted policies. One is the case you identify -- distance from capturing library to pickup library -- for which the cached value is accurate only when the item circ lib is the capturing lib (well, except for system-level adjustment which widens the net of accuracy, but we'll go with the strictest possible config for this thought experiment). That case is, in practice, overwhelmingly common [though, of course, I encourage all to check their own data on that], but is also not the only case.

However, it's not true that the only valid policy is meant to model the capture<->pickup distance. First, it is relatively common that the ownership of an item by a particular location is more important than where it happens to be at any given moment when deciding to whom it should be loaned next. Take the case of peering agreements between two library systems within a broader consortium, or regional agreements to be lenders of first resort.

But, that's not the whole story, of course. The obvious reason we cache, and make available, the home<->pickup calculated proximity is because that's what we /can/ know up front. It's a useful value that we can store for later and avoid having to recalculate it over and over. But that is not the only value that can be generated by the code that Lebbeous posted. Indeed, the capture<->pickup proximity /can/ be calculated by that code, and the code posted is only one part of the larger work we're doing. Specifically, we have already worked out exactly how to make use of the calculated capture<->pickup proximity. The only outstanding potential problem we foresee is the speed of calculating that on the fly at the time of best-hold selection. It may turn out to be a non-issue and be plenty fast, of course, which is what it looks like today, but if it is expensive in the context of an item that could fill many holds (probably only relevant when fillable holds are on the order of thousands, but testing will tell), then we will document that fact so that users of the feature can make an informed decision between the two (well, many more, but here presented, two) angles from which to view proximity -- political policy, or physical capture time distance.

There are technical solutions, of one manner or another, to that problem as well, if it exists. Testing of other, future code will show if the medicine is needed, and whether it's better or worse than the disease. We've tried to foresee as many issues as possible to provide a solid implementation, and the question Thomas raises is one of those questions, but isn't addressable directly by /this/ code and so is left to later code that can address it.

The second part of the project, Custom Best-hold Selection Order, is what will allow the library to choose from many different points of view, with the code posted here supporting several of those.

And you're correct about FulfILLment, Thomas. It does have the advantage of being able to assume more about the capture location, but that just means it was an easier home for the first generation of this code, not that it can't be improved and refactored for use in Evergre...

[Thomas Berezansky (tsbere)]

At this point I see two semi-obvious issues with the code (I have not tried to run it yet):

1 - It assumes that the calculated and cached proximity is the desired one whenever it is present, despite the fact that the *current* method uses the checkin location proximity rather than a copy-based proximity. This effectively throws out the entirety of the current method of proximity detection with no obvious way to use the old one at this time. Yes, this may be desired by some groups, but not all, and definitely not those of us looking to keep the actual number of transits to a minimum whenever possible under normal conditions.

I know that you have made the argument that other work being done will make this distinction possible. Based on that I say the following: Until that work is also available I think that this work needs to be able to make that distinction available or the pullrequest should be removed. If the "second part" depends on this part then they should be tested and merged *together* instead of individually, otherwise it is a wholesale change of how holds target and fill that has no off switch and no configuration that can maintain the current behavior.

2 - Holds don't have a "prox" field, to my knowledge, and the COALESCE in the nearest copy function order by sets seems to be looking for one. I suspect this is more of a typo and p.prox was intended.

[Mike Rylander (mrylander)]

Thomas,

1 - Feel free to ignore the code, you needn't be the one to test or merge it, and in fact there is no plan to merge this branch independent of the forthcoming branch. The intention is to get the code out there and in front of eyes as soon as possible. Seems to me that was accomplished, even if those eyes would rather have not seen it until the part was published. :)

2 - It looks like that is indeed a typo. Good catch. (Though, and I'm sure this is obvious, that's exactly the code set to be replaced by the aforementioned "other branch".)

[Lebbeous Fogle-Weekley (lebbeous)]

Indeed. Removed pullrequest tag for now. That was just force of habit. Branch for the custom best-hold selection sort order work will also go here when ready (soon).

[Lebbeous Fogle-Weekley (lebbeous)]

So instead of having a separate branch and bug for both calculated proximity adjustment and custom best-hold-sort-selection order, they really ought to be combined, since they're so interrelated.

And here that branch is, squashed to two commits and freshly rebased against master.

http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/senator/calc-prox-and-custom-best-hold-whole-shebang

What's custom best-hold sort selection you ask? See the tech spec documents in the branch! Play with the interface. Fun times for all.

[Lebbeous Fogle-Weekley (lebbeous)]

Freshly rebased against master, with a tiny fix to the seed data for fresh DB installations.

http://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/user/senator/calc-prox-and-custom-best-hold-update

[Mike Rylander (mrylander)]

Merge to master with minor conflicts addressed.