<commit_before><commit_msg>documentation of the global purchasing capability<commit_after>=================
Global purchasing
=================

By default the planning algorithm will trigger a replenishment for a
buffer as soon as its inventory level drops below the safety stock.
This logic is based on the local needs at the buffer. 

In a distribution network with inventory at multiple locations, 
considering the inventory across the entire network for the purchasing 
decisions can significantly reduce the inventory and obsolesence costs.  

Using the global purchase flag we can prevent a new purchase order
to be created when sufficient inventory is still available at other
locations in the network. And it directs demands to locations that
have available inventory.

This feature has 2 specific planning behavior:

* | Generation of a new purchase order for an item is blocked when 
    the total inventory of the item across all locations is above the 
    sum of the safety stock of the item across all locations.

* | By default frePPLe *only* plans a demand on the location where it is
    pointing at. 
  | When the global_purchase flag for the item is set, the
    planning algorithm will first plan at the demand location. If the
    demand can't be satisfied from that location the algorithm will try to
    satisfy the demand from other locations that have the item on stock.
    Candidate locations are sorted in descending order by the amount
    inventory above the safety stock level they carry of the item.

*******
Example
*******

Imagine a distribution network with inventory at a number of warehouses
across the country for a particular item:

======== ========= ============
Location Inventory Safety stock
======== ========= ============
WH1      100       10
WH2      0         10
WH3      20        10
======== ========= ============
 
A sales order from a customer close to WH2 can easily be shipped from
WH1 instead. With the global_purchase flag set, we will automatically 
redirect the demand to WH1 (which has highest inventory above its safety
stock) and WH3.

Any new purchase orders for this item are deplayed until the total 
inventory across all location drops below 30 = 10 + 10 + 10.
    
{'fraction_non_alphanumeric': 0.07699194270367055, 'fraction_numerical': 0.012533572068039392, 'mean_word_length': 3.933774834437086, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3418623', 'n_tokens_mistral': 525, 'n_tokens_neox': 495, 'n_words': 323}