@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/Allocation_Optimization/Allocation_LP.js

@@ -0,0 +1,150 @@
+const { Optimizer } = require('@jetta/lp-framework')
+const Optimization_Infeasible_Exception = require('./exceptions/Optimization_Infeasible_Exception')
+const LP_Data_Processor = require('./lp_model/LP_Data_Processor')
+const LP_Model_Builder = require('./lp_model/model_builder/LP_Model_Builder')
+const LP_Result_Mapper = require('./lp_model/LP_Result_Mapper')
+const has_relational_items = require('../relational/has_relational_items')
+const Cargo_Profile = require('../models/Cargo_Profile')
+const { enrich_optimizer_http_error } = require('../optimizer_connection_errors')
+const { is_lp_optimizer_result_success } = require('../lp_optimizer_result_status')
+const { traced_step } = require('../tracing/traced_step')
+const { TRACE_CONTEXT } = require('../tracing/Trace_Context')
+/**
+ * @class Allocation_LP
+ * @description Orchestrates the Linear Programming model for block allocation; see `<root_project>/doc/LP`.
+ */
+class Allocation_LP
+{
+    #container
+    #space_to_allocate
+    #block_list
+    #block_amount_map
+    #item_list
+    #block_map = {}
+    constructor(
+        container,
+        space_to_allocate,
+        block_list,
+        block_amount_map,
+        item_list
+    )
+    {
+        this.#container = container
+        this.#space_to_allocate = space_to_allocate
+        this.#block_amount_map = block_amount_map
+        this.#item_list = item_list
+        this.#block_list = this.#unique_blocks(block_list)
+        this.#block_list.forEach(block => this.#block_map[block.get_id()] = block)
+    }
+    /**
+     * Orchestrates the Linear Programming model for block allocation,
+     * attempting to find an optimal solution first with a uniformity penalty,
+     * and falling back to an allocation without the uniformity penalty if the first attempt fails.
+     * @returns {Promise<object>} The mapped result of the optimization.
+     * @throws {Optimization_Infeasible_Exception} If no feasible solution can be found in either attempt.
+     */
+    async optimize()
+    {
+        return traced_step(TRACE_CONTEXT.LP_OPTIMIZE, async () => this.#optimize_without_trace())
+    }
+
+    async #optimize_without_trace()
+    {
+        // Attempt 1: Optimize with uniformity penalty (skipped when single-item-type or uniform
+        // block measure is enforced, since those caps already collapse dimensional variety).
+        if (
+            Cargo_Profile.enable_block_equalization()
+            && !Cargo_Profile.enforce_single_item_type()
+            && !Cargo_Profile.enforce_uniform_block_measure()
+        )
+        {
+            const result_with_uniformity = await this.#run_optimization_attempt(true)
+            if (this.#is_optimization_feasible(result_with_uniformity))
+            {
+                return result_with_uniformity
+            }
+        }
+        // Attempt 2: Optimize without uniformity penalty (fallback)
+        const result_without_uniformity = await this.#run_optimization_attempt(false)
+        if (this.#is_optimization_feasible(result_without_uniformity))
+        {
+            return result_without_uniformity
+        }
+        throw new Optimization_Infeasible_Exception()
+    }
+    #is_optimization_feasible(result)
+    {
+        return result && result.chosen_blocks.length > 0
+    }
+    #build_model(enable_uniformity_penalty)
+    {
+        const optimizer = new Optimizer(undefined, true)
+        const model_builder = new LP_Model_Builder({
+            optimizer,
+            container: this.#container,
+            empty_space: this.#space_to_allocate,
+            block_list: this.#block_list,
+            item_list: this.#item_list,
+            block_amount_map: this.#block_amount_map,
+            enable_uniformity_penalty
+        })
+        model_builder.build_model()
+        return {
+            optimizer,
+            item_assignment_context: model_builder.get_item_assignment_context()
+        }
+    }
+    async #run_optimization_attempt(enable_uniformity_penalty)
+    {
+        const { optimizer, item_assignment_context } = this.#build_model(enable_uniformity_penalty)
+        const optimization_start_ms = Date.now()
+        let result
+        try
+        {
+            result = await optimizer.optimize()
+        }
+        catch (error)
+        {
+            throw enrich_optimizer_http_error(
+                error,
+                Date.now() - optimization_start_ms,
+                this.#block_list.length,
+                optimizer.restriction_list?.length ?? -1
+            )
+        }
+        const status = result.status()
+        if (is_lp_optimizer_result_success(status))
+        {
+            const context_for_mapper = should_use_lp_item_assignment(this.#item_list)
+                ? item_assignment_context
+                : null
+            const result_mapper = new LP_Result_Mapper(this.#block_map)
+            return result_mapper.map_result(result, context_for_mapper)
+        }
+        return null
+    }
+    #unique_blocks(to_clean)
+    {
+        const data_processor = new LP_Data_Processor()
+        const sanitized_blocks = data_processor.sanitize(to_clean, this.#block_amount_map)
+        const unique_blocks = data_processor.remove_duplicates(sanitized_blocks)
+        return unique_blocks
+    }
+}
+
+function should_use_lp_item_assignment(item_list)
+{
+    if (Cargo_Profile.relational_lp_require_exact_pass_amount() && has_relational_items(item_list))
+    {
+        return true
+    }
+
+    if (!Cargo_Profile.enforce_relational_group_co_location())
+    {
+        return false
+    }
+
+    return has_relational_items(item_list)
+}
+
+module.exports = Allocation_LP

package/src/Allocation_Optimization/Block_Allocator.js

@@ -0,0 +1,129 @@
+const Allocation_LP                   = require('./Allocation_LP')
+const cap_chosen_blocks_by_stock_budget = require('./Chosen_Blocks_Stock_Cap')
+const cap_chosen_blocks_by_shape_stock = require('./cap_chosen_blocks_by_shape_stock')
+const No_Valid_Allocation_Exception   = require('./exceptions/No_Valid_Allocation_Exception')
+const Block_Builder                   = require('./block_builder/Blocks_Builder')
+const { order_chosen_blocks_for_layer } = require('./Block_Layer_Order')
+const resolve_next_group_id = require('./next_group_id_after_preloaded')
+
+class Block_Allocator
+{
+    #next_group_id = 0
+
+    async optimize_and_allocate
+    (
+        container,
+        space_to_allocate,
+        block_list,
+        item_amount_map,
+        item_list,
+        block_amount_map,
+        effective_item_list,
+        picking_continuity_seed
+    )
+    {
+        this.#next_group_id = resolve_next_group_id(container, this.#next_group_id)
+        const lp_item_list = effective_item_list ?? item_list
+        const optimized_blocks = await this.#optimize_block_layer(
+            container,
+            space_to_allocate,
+            block_list,
+            block_amount_map,
+            lp_item_list
+        )
+
+        const ordered_blocks = order_chosen_blocks_for_layer(
+            optimized_blocks.chosen_blocks,
+            container,
+            lp_item_list
+        )
+        const capped_by_budget = cap_chosen_blocks_by_stock_budget(ordered_blocks, item_list, container)
+        const capped_blocks = cap_chosen_blocks_by_shape_stock(capped_by_budget, item_list)
+
+        const block_builder_output = this.#build_blocks(
+            space_to_allocate,
+            { chosen_blocks: capped_blocks },
+            item_list,
+            item_amount_map,
+            container,
+            picking_continuity_seed,
+            optimized_blocks.block_instance_item_queues
+        )
+
+        if (block_builder_output.allocated_item_list.length === 0)
+        {
+            throw new No_Valid_Allocation_Exception()
+        }
+
+        return block_builder_output
+    }
+
+
+    async #optimize_block_layer(
+        container,
+        space_to_allocate,
+        block_list,
+        block_amount_map,
+        items_to_allocate
+    )
+    {
+        const LP = new Allocation_LP(
+            container,
+            space_to_allocate,
+            block_list,
+            block_amount_map,
+            items_to_allocate
+        )
+
+        return await LP.optimize()
+    }
+
+    #build_blocks(
+        space_to_allocate,
+        optimized_block_layer,
+        item_list,
+        item_amount_map,
+        container,
+        picking_continuity_seed,
+        block_instance_item_queues
+    )
+    {
+        const block_builder_data = this.#create_blocks_builder_data(
+            space_to_allocate,
+            optimized_block_layer,
+            item_list,
+            item_amount_map,
+            container,
+            picking_continuity_seed
+        )
+        block_builder_data.block_instance_item_queues = block_instance_item_queues ?? new Map()
+        const block_builder        = new Block_Builder(block_builder_data)
+        const block_builder_output = block_builder.get_allocated_item_list()
+        this.#next_group_id = block_builder_output.next_group_id
+        return block_builder_output
+    }
+
+    #create_blocks_builder_data(
+        space_to_allocate,
+        optimized_block_layer,
+        item_list,
+        item_amount_map,
+        container,
+        picking_continuity_seed
+    )
+    {
+        return {
+            space_to_allocate: space_to_allocate,
+            optimized_block_layer: optimized_block_layer,
+            item_list: item_list,
+            item_amount_map: item_amount_map,
+            container: container,
+            picking_continuity_seed: picking_continuity_seed,
+            next_group_id: this.#next_group_id
+        }
+    }
+
+
+}
+
+module.exports = Block_Allocator

package/src/Allocation_Optimization/Block_Layer_Order.js

@@ -0,0 +1,50 @@
+const { get_weight_utilization, get_space_utilization } = require('./density_groups/Container_Utilization')
+const { calculate_block_potential_weight, get_dimension_to_max_weight_map } = require('./Block_Potential_Weight')
+
+/**
+ * Sorts chosen LP blocks for block builder consumption.
+ * @param {{ block: object, amount: number }[]} chosen_blocks - LP output.
+ * @param {object} container - Current container.
+ * @param {object[]} item_list - Items available for weight estimation.
+ * @returns {{ block: object, amount: number }[]}
+ */
+function order_chosen_blocks_for_layer(chosen_blocks, container, item_list)
+{
+    const block_choices = Array.from(chosen_blocks)
+    if (block_choices.length <= 1)
+    {
+        return block_choices
+    }
+
+    const weight_utilization = get_weight_utilization(container)
+    const space_utilization = get_space_utilization(container)
+    if (weight_utilization <= space_utilization)
+    {
+        return block_choices.sort((block_b, block_a) => block_b.block.get_volume() - block_a.block.get_volume())
+    }
+
+    const dimension_to_max_weight_map = get_dimension_to_max_weight_map(item_list)
+    return block_choices.sort((block_b, block_a) =>
+    {
+        const ratio_b = get_volume_to_weight_ratio(block_b.block, dimension_to_max_weight_map)
+        const ratio_a = get_volume_to_weight_ratio(block_a.block, dimension_to_max_weight_map)
+        return ratio_a - ratio_b
+    })
+}
+
+/**
+ * @param {object} block
+ * @param {Map<string, number>} dimension_to_max_weight_map
+ * @returns {number}
+ */
+function get_volume_to_weight_ratio(block, dimension_to_max_weight_map)
+{
+    const potential_weight = calculate_block_potential_weight(block, dimension_to_max_weight_map)
+    if (potential_weight <= 0)
+    {
+        return block.get_volume()
+    }
+    return block.get_volume() / potential_weight
+}
+
+module.exports = { order_chosen_blocks_for_layer }

package/src/Allocation_Optimization/Block_Potential_Weight.js

@@ -0,0 +1,54 @@
+const {
+    get_dimension_hash,
+    collect_rotation_dimension_hashes
+} = require('./lp_model/model_builder/item_dimension_hashes')
+
+/**
+ * Maps each dimension hash to the max item weight for that hash.
+ * @param {object[]} item_list - An array of Item objects.
+ * @returns {Map<string, number>} Hash to max weight.
+ */
+function get_dimension_to_max_weight_map(item_list)
+{
+    const dimension_to_max_weight_map = new Map()
+
+    for (const item of item_list)
+    {
+        const weight = item.get_weight()
+        const rotation_hashes = collect_rotation_dimension_hashes(item)
+
+        for (const hash of rotation_hashes)
+        {
+            const current_max_weight = dimension_to_max_weight_map.get(hash) || 0
+
+            if (weight > current_max_weight)
+            {
+                dimension_to_max_weight_map.set(hash, weight)
+            }
+        }
+    }
+    return dimension_to_max_weight_map
+}
+
+/**
+ * Calculates the maximum potential weight of a block by summing slot max weights.
+ * @param {object} block - The block to analyze.
+ * @param {Map<string, number>} dimension_to_max_weight_map - Hash to max weight.
+ * @returns {number}
+ */
+function calculate_block_potential_weight(block, dimension_to_max_weight_map)
+{
+    let block_potential_weight = 0
+    for (const slot of block.get_slot_list())
+    {
+        const slot_hash = get_dimension_hash(slot)
+        const max_weight_for_slot = dimension_to_max_weight_map.get(slot_hash) || 0
+        block_potential_weight += max_weight_for_slot
+    }
+    return block_potential_weight
+}
+
+module.exports = {
+    get_dimension_to_max_weight_map,
+    calculate_block_potential_weight
+}

package/src/Allocation_Optimization/Chosen_Blocks_Stock_Cap.js

@@ -0,0 +1,82 @@
+/**
+ * Sums remaining allocatable units across items.
+ * @param {object[]} item_list - Items with get_amount().
+ * @returns {number}
+ */
+function sum_item_amounts(item_list)
+{
+    return item_list.reduce(
+        (running_sum, item) => running_sum + Math.max(0, Math.floor(Number(item.get_amount()) || 0)),
+        0,
+    )
+}
+
+/**
+ * Minimum item weight among SKUs with positive amount (pessimistic load per slot).
+ * @param {object[]} item_list - Items with get_amount() and get_weight().
+ * @returns {number} Zero when no stock (weight cap skipped).
+ */
+function minimum_weight_among_available_items(item_list)
+{
+    let minimum_weight = null
+    for (let i = 0; i < item_list.length; i += 1)
+    {
+        const item = item_list[i]
+        if (item.get_amount() <= 0)
+        {
+            continue
+        }
+        const item_weight = item.get_weight()
+        if (minimum_weight === null || item_weight < minimum_weight)
+        {
+            minimum_weight = item_weight
+        }
+    }
+    return minimum_weight === null ? 0 : minimum_weight
+}
+
+/**
+ * Trims chosen block instance counts using item stock and container supported weight
+ * (pessimistic: each slot carries at least the lightest in-stock SKU). Preserves caller order.
+ *
+ * @param {{ block: object, amount: number }[]} chosen_blocks - Block choices in execution order.
+ * @param {object[]} item_list - Current items with amounts.
+ * @param {object} container - Container with supported_weight().
+ * @returns {{ block: object, amount: number }[]}
+ */
+module.exports = function cap_chosen_blocks_by_stock_budget(chosen_blocks, item_list, container)
+{
+    let slot_budget = sum_item_amounts(item_list)
+    const minimum_weight = minimum_weight_among_available_items(item_list)
+    let weight_budget = typeof container.supported_weight === 'function'
+        ? container.supported_weight()
+        : container.supported_weight
+    const capped_block_choices = []
+
+    for (const choice of chosen_blocks)
+    {
+        const slots_per_block = choice.block.get_slot_list().length
+        const requested = Math.floor(Number(choice.amount) || 0)
+        if (slots_per_block === 0 || requested === 0)
+        {
+            continue
+        }
+        const maximum_by_stock = Math.floor(slot_budget / slots_per_block)
+        const load_per_instance = minimum_weight > 0 ? slots_per_block * minimum_weight : 0
+        const maximum_by_weight = load_per_instance > 0
+            ? Math.floor(weight_budget / load_per_instance)
+            : Number.POSITIVE_INFINITY
+        const allowed_instance_count = Math.min(requested, maximum_by_stock, maximum_by_weight)
+        if (allowed_instance_count > 0)
+        {
+            capped_block_choices.push({ block: choice.block, amount: allowed_instance_count })
+            slot_budget -= allowed_instance_count * slots_per_block
+            if (load_per_instance > 0)
+            {
+                weight_budget -= allowed_instance_count * load_per_instance
+            }
+        }
+    }
+
+    return capped_block_choices
+}

package/src/Allocation_Optimization/block_builder/Allocation_Item_Creator.js

@@ -0,0 +1,37 @@
+const Allocation_Item = require('../../models/Allocation_Item')
+
+function assign_block_metadata_to_items(group_id, tie_ratio_orientation, items_in_block)
+{
+    items_in_block.forEach(item =>
+    {
+        if (group_id !== undefined)
+        {
+            item.set_group_id(group_id)
+        }
+        if (tie_ratio_orientation !== undefined)
+        {
+            item.set_tie_ratio_orientation(tie_ratio_orientation)
+        }
+    })
+}
+
+module.exports = function create_allocated_item(group_id, block, items_in_block, block_position)
+{
+    const tie_ratio_orientation = block.get_tie_ratio_orientation()
+    assign_block_metadata_to_items(group_id, tie_ratio_orientation, items_in_block)
+    const block_weight    = items_in_block.reduce((sum, item) => sum + item.get_weight(), 0)
+    const block_json      = block.get_json()
+    block_json['weight']  = block_weight
+    if (group_id !== undefined)
+    {
+        block_json['groupId'] = group_id
+    }
+    if (tie_ratio_orientation !== undefined)
+    {
+        block_json['tie_ratio_orientation'] = tie_ratio_orientation
+    }
+    const allocation_item = new Allocation_Item(block_json)
+    allocation_item.sum_position_vector(block_position)
+    const allocated_item  = allocation_item.get_item_as_positioned_cube()
+    return allocated_item
+}

package/src/Allocation_Optimization/block_builder/Block_Item_List_Validator.js

@@ -0,0 +1,18 @@
+const Empty_Block_Item_List_Exception = require('./exceptions/Empty_Block_Item_List_Exception')
+
+/**
+ * Ensures a block build produced at least one allocated item before side effects run.
+ * @param {object} block - Block whose slots were assigned.
+ * @param {object[]} item_in_block_list - Items assigned to the block slots.
+ * @throws {Empty_Block_Item_List_Exception} When no items were allocated.
+ */
+function assert_non_empty_item_list(block, item_in_block_list)
+{
+    if (item_in_block_list.length === 0)
+    {
+        const slot_count = block.get_slot_list().length
+        throw new Empty_Block_Item_List_Exception(block.get_id(), slot_count)
+    }
+}
+
+module.exports = { assert_non_empty_item_list }