@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/Allocation_Optimization/block_builder/Block_Wall_Builder.js

@@ -0,0 +1,303 @@
+const assign_item_to_slots = require('./Slot_Item_Assigner')
+const calculate_next_block_position = require('./Next_Block_Position')
+const create_allocated_item_from_block = require('./Allocation_Item_Creator')
+const { assert_non_empty_item_list } = require('./Block_Item_List_Validator')
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const apply_loose_placement_to_allocated_item = require('../tie_ratio/loose_on_block/apply_loose_placement_to_allocated_item')
+const { finalize_loose_item_placement } = require('../tie_ratio/loose_on_block/finalize_loose_item_placement')
+const { create_loose_on_block_slot_state } = require('../tie_ratio/loose_on_block/loose_on_block_slot_state')
+const No_Suitable_Item_Exception = require('./exceptions/No_Suitable_Item_Exception')
+const Restricted_Block_Exception = require('./exceptions/Restricted_Block_Exception')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+const assert_tie_ratio_block_matches_orientation_below = require('./assert_tie_ratio_block_matches_orientation_below')
+const snap_elevated_block_wall_items = require('./snap_elevated_block_wall_items')
+const should_omit_block_group_id = require('./should_omit_block_group_id')
+const allocated_items_weight_sum = (item_list) => item_list.reduce((acc, item) => acc + item.get_weight(), 0)
+
+/**
+ * Builds all block instances for one optimized wall layer.
+ * @param {object} wall_data
+ * @param {number} [wall_data.next_group_id=0] - Seed for the first block group id in this wall.
+ * @returns {object} Wall output including `next_group_id` after the last built block.
+ */
+function build_allocated_wall(wall_data)
+{
+    const output = create_empty_wall_output()
+    let state = create_initial_wall_state(wall_data)
+    for (const choice of wall_data.optimized_block_layer.chosen_blocks)
+    {
+        state = build_blocks_for_choice(choice, wall_data, state, output)
+    }
+    output.last_allocated_item_id = Cargo_Profile.prefer_block_with_same_item()
+        ? (state.last_chosen_item_id ?? null)
+        : null
+    output.next_group_id = state.next_group_id
+    return output
+}
+
+function create_empty_wall_output()
+{
+    return {
+        allocated_item_list: [],
+        item_to_find_space_list: [],
+        single_slot_allocated_item_ids: new Set(),
+        last_allocated_item_id: null,
+        placed_tie_ratio_block: false
+    }
+}
+
+function create_initial_wall_state(wall_data)
+{
+    return {
+        current_block_position: wall_data.space_to_allocate,
+        container_supported_weight: wall_data.container.supported_weight(),
+        item_position: get_item_position(wall_data.space_to_allocate),
+        last_chosen_item_id: resolve_continuity_seed(wall_data.picking_continuity_seed),
+        next_group_id: wall_data.next_group_id ?? 0,
+        loose_on_block_slot_state: create_loose_on_block_slot_state()
+    }
+}
+
+function resolve_continuity_seed(seed_item_id)
+{
+    if (!Cargo_Profile.prefer_block_with_same_item())
+    {
+        return undefined
+    }
+    return seed_item_id ?? undefined
+}
+
+function get_item_position(space)
+{
+    return { x: space.get_x(), y: space.get_y(), z: space.get_z() }
+}
+
+function build_blocks_for_choice(choice, wall_data, state, output)
+{
+    const chosen_block = choice.block
+    const amount = choice.amount | 0
+    const is_single_slot = chosen_block.get_slot_list().length === 1
+    let next_state = state
+    for (let index = 0; index < amount; index++)
+    {
+        next_state = build_one_block_instance(chosen_block, is_single_slot, wall_data, next_state, output)
+    }
+    return next_state
+}
+
+function build_one_block_instance(chosen_block, is_single_slot, wall_data, state, output)
+{
+    const builder_output = build_a_block(
+        chosen_block,
+        is_single_slot,
+        state,
+        wall_data,
+        output.allocated_item_list
+    )
+    assert_non_empty_item_list(chosen_block, builder_output.item_in_block_list)
+    append_block_to_output(builder_output, is_single_slot, chosen_block, wall_data, output)
+    if (typeof chosen_block.is_tie_ratio_block === 'function' && chosen_block.is_tie_ratio_block())
+    {
+        output.placed_tie_ratio_block = true
+    }
+    return advance_wall_state(state, builder_output)
+}
+
+function build_a_block(chosen_block, is_single_slot, state, wall_data, pending_wall_allocated_items)
+{
+    const item_position = resolve_single_slot_item_position(state, wall_data, is_single_slot)
+    try
+    {
+        assert_tie_ratio_block_matches_orientation_below(
+            wall_data.container,
+            item_position,
+            chosen_block
+        )
+    }
+    catch (error)
+    {
+        throw_restricted_block_exception(error, wall_data, chosen_block)
+    }
+    const item_in_block_list = assign_item_to_slots(
+        wall_data.heuristic,
+        chosen_block,
+        wall_data.allocated_blocks_amount,
+        state.container_supported_weight,
+        item_position,
+        state.last_chosen_item_id
+    )
+    let realigned_item_list = item_in_block_list
+    try
+    {
+        const snapped_item_list = skip_elevated_snap_for_loose_unitary(is_single_slot)
+            ? item_in_block_list
+            : snap_elevated_block_wall_items(
+                item_in_block_list,
+                wall_data,
+                pending_wall_allocated_items
+            )
+        realigned_item_list = realign_single_slot_loose_items(
+            snapped_item_list,
+            is_single_slot,
+            wall_data,
+            state,
+            pending_wall_allocated_items
+        )
+    }
+    catch (error)
+    {
+        throw_restricted_block_exception(error, wall_data, chosen_block)
+    }
+    const group_id = allocate_next_group_id(chosen_block, state, wall_data)
+    const block_as_item = create_allocated_item_from_block(
+        group_id,
+        chosen_block,
+        realigned_item_list,
+        state.current_block_position
+    )
+    const next_block_position = calculate_next_block_position(
+        state.current_block_position,
+        chosen_block
+    )
+    return { item_in_block_list: realigned_item_list, block_as_item, next_block_position }
+}
+
+function skip_elevated_snap_for_loose_unitary(is_single_slot)
+{
+    return is_single_slot === true && Cargo_Profile.stack_loose_on_tie_ratio_blocks()
+}
+
+function throw_restricted_block_exception(error, wall_data, chosen_block)
+{
+    if (!(error instanceof No_Suitable_Item_Exception))
+    {
+        throw error
+    }
+    const block_id = chosen_block.get_id()
+    const max_amount = wall_data.allocated_blocks_amount[block_id] ?? 0
+    throw new Restricted_Block_Exception({ id: block_id, restrict_to: max_amount })
+}
+
+function realign_single_slot_loose_items(
+    item_in_block_list,
+    is_single_slot,
+    wall_data,
+    state,
+    pending_wall_allocated_items
+)
+{
+    if (!is_single_slot || !Cargo_Profile.stack_loose_on_tie_ratio_blocks())
+    {
+        return item_in_block_list
+    }
+    return item_in_block_list.map(allocated_item =>
+    {
+        const relocated_item = apply_loose_placement_to_allocated_item(
+            allocated_item,
+            wall_data.container,
+            wall_data.space_to_allocate,
+            state.loose_on_block_slot_state,
+            wall_data.supporters_by_top_y_index,
+            pending_wall_allocated_items
+        )
+        if (relocated_item === undefined)
+        {
+            throw new No_Suitable_Item_Exception(ALLOCATOR_MESSAGE.LOOSE_ON_TIE_RATIO_FAILED)
+        }
+        const finalized_item = finalize_loose_item_placement(
+            relocated_item,
+            wall_data,
+            pending_wall_allocated_items
+        )
+        if (finalized_item === undefined)
+        {
+            throw new No_Suitable_Item_Exception(ALLOCATOR_MESSAGE.LOOSE_ON_TIE_RATIO_FAILED)
+        }
+        return finalized_item
+    })
+}
+
+function resolve_single_slot_item_position(state, _wall_data, _is_single_slot)
+{
+    return state.item_position
+}
+
+function allocate_next_group_id(chosen_block, state, wall_data)
+{
+    const wall_height_y = wall_data.space_to_allocate.get_y()
+    if (should_omit_block_group_id(chosen_block, wall_height_y))
+    {
+        return undefined
+    }
+    state.next_group_id += 1
+    return state.next_group_id
+}
+
+function append_block_to_output(builder_output, is_single_slot, chosen_block, wall_data, output)
+{
+    output.allocated_item_list.push(...builder_output.item_in_block_list)
+    register_single_slot_item(output.single_slot_allocated_item_ids, is_single_slot, builder_output.item_in_block_list)
+    register_successful_block(wall_data.allocated_blocks_amount, chosen_block)
+    append_find_space_items(output.item_to_find_space_list, builder_output)
+}
+
+function advance_wall_state(state, builder_output)
+{
+    const last_item = builder_output.item_in_block_list.at(-1)
+    const next_seed = resolve_continuity_seed(last_item.get_id())
+    return {
+        current_block_position: builder_output.next_block_position,
+        container_supported_weight: state.container_supported_weight
+            - allocated_items_weight_sum(builder_output.item_in_block_list),
+        item_position: update_item_position(builder_output.next_block_position),
+        last_chosen_item_id: next_seed,
+        next_group_id: state.next_group_id,
+        loose_on_block_slot_state: state.loose_on_block_slot_state
+    }
+}
+
+function register_single_slot_item(set, is_single_slot, item_list)
+{
+    if (!is_single_slot || item_list.length === 0)
+    {
+        return
+    }
+    set.add(item_list[0].get_id())
+}
+
+function register_successful_block(amount_map, block)
+{
+    if (!block)
+    {
+        return
+    }
+    const block_id = block.get_id()
+    amount_map[block_id] = (amount_map[block_id] ?? 0) + 1
+}
+
+function update_item_position(position)
+{
+    return { x: position.get_x(), y: position.get_y(), z: position.get_z() }
+}
+
+function append_find_space_items(list, builder_output)
+{
+    const block_item = builder_output.block_as_item
+    const use_outline = should_use_block_outline(block_item)
+    if (use_outline)
+    {
+        list.push(block_item)
+        return
+    }
+    list.push(...builder_output.item_in_block_list)
+}
+
+function should_use_block_outline(block_item)
+{
+    const spiral_enabled = Cargo_Profile.enable_to_find_empty_space_from_spiral_block_of_same_measure()
+    const block_enabled = Cargo_Profile.enable_to_find_empty_space_block()
+    const uniform_slots = block_item.is_block_with_slots_of_same_measure()
+    return block_enabled || (spiral_enabled && uniform_slots)
+}
+
+module.exports = { build_allocated_wall }

package/src/Allocation_Optimization/block_builder/Blocks_Builder.js

@@ -0,0 +1,40 @@
+const Slots_Items_Assigner = require('../item_consumption_heuristic/Slots_Items_Assigner')
+const { build_allocated_wall } = require('./Block_Wall_Builder')
+const { traced_step_sync } = require('../../tracing/traced_step')
+const { TRACE_CONTEXT } = require('../../tracing/Trace_Context')
+
+module.exports = class Block_Builder
+{
+    #wall_data
+
+    constructor(block_builder_data)
+    {
+        this.#wall_data = {
+            space_to_allocate: block_builder_data.space_to_allocate,
+            optimized_block_layer: block_builder_data.optimized_block_layer,
+            container: block_builder_data.container,
+            picking_continuity_seed: block_builder_data.picking_continuity_seed,
+            block_instance_item_queues: block_builder_data.block_instance_item_queues ?? new Map(),
+            heuristic: new Slots_Items_Assigner(
+                block_builder_data.space_to_allocate,
+                block_builder_data.item_list,
+                block_builder_data.item_amount_map.copy(),
+                block_builder_data.container
+            ),
+            allocated_blocks_amount: {},
+            next_group_id: block_builder_data.next_group_id ?? 0
+        }
+    }
+
+    /**
+     * @returns {object}
+     */
+    get_allocated_item_list()
+    {
+        return traced_step_sync(TRACE_CONTEXT.ITEM_SELECTION_POSITIONING, () =>
+            traced_step_sync(TRACE_CONTEXT.CHOSEN_BLOCK_STACKING_VALIDATION, () =>
+                build_allocated_wall(this.#wall_data)
+            )
+        )
+    }
+}

package/src/Allocation_Optimization/block_builder/Next_Block_Position.js

@@ -0,0 +1,33 @@
+const { Space }         = require('@jetta/empty-spaces-manager')
+const { LENGTH, WIDTH } = require('../functions/measure_to_optimize')
+const round             = require('../../tools/Rounder')
+const { read_measure_to_be_optimized } = require('../functions/Measure_Reader')
+
+module.exports = function next_block_position(current_block_position, block)
+{
+    switch (read_measure_to_be_optimized())
+    {
+        case LENGTH:
+            const block_length = Number(block.get_length())
+            return create_space(current_block_position, block_length, LENGTH)
+        case WIDTH:
+        default:
+            const block_width = Number(block.get_width())
+            return create_space(current_block_position, block_width, WIDTH)
+    }
+}
+
+function create_space(current_space, increase, type)
+{
+    const x = type === WIDTH ? round(current_space.get_x() + increase) : current_space.get_x()
+    const z = type === LENGTH ? round(current_space.get_z() + increase) : current_space.get_z()
+
+    return new Space({
+        x,
+        y: current_space.get_y(),
+        z,
+        width: current_space.get_width(),
+        height: current_space.get_height(),
+        length: current_space.get_length()
+    })
+}

package/src/Allocation_Optimization/block_builder/Slot_Item_Assigner.js

@@ -0,0 +1,45 @@
+const Restricted_Block_Exception = require('./exceptions/Restricted_Block_Exception')
+const No_Suitable_Item_Exception = require('./exceptions/No_Suitable_Item_Exception')
+const { Logger } = require('@jetta/logger')
+const logger = new Logger('Slot Item Assigner')
+
+module.exports = function assign_item_to_slots(
+    heuristic,
+    block,
+    allocated_blocks_amount,
+    container_supported_weight,
+    item_position,
+    picking_continuity_seed
+)
+{
+    try
+    {
+        const assigned_item_list = heuristic.assign_items_to_slots(
+            block,
+            container_supported_weight,
+            item_position,
+            picking_continuity_seed
+        )
+        return assigned_item_list
+    }
+    catch (error)
+    {
+        throw_restricted_block_exception(error, allocated_blocks_amount, block)
+    }
+}
+
+function throw_restricted_block_exception(error, allocated_blocks_amount, block)
+{
+    if (error instanceof No_Suitable_Item_Exception)
+    {
+        logger.warn(error.message)
+        const sucessfull_blocks_amount = allocated_blocks_amount[block.get_id()]
+        const max_amount = sucessfull_blocks_amount == undefined ? 0 : sucessfull_blocks_amount
+        const block_to_restrict = {
+            'id':block.get_id(),
+            'restrict_to': max_amount
+        }
+        throw new Restricted_Block_Exception(block_to_restrict)
+    }
+    throw error
+}

package/src/Allocation_Optimization/block_builder/Stacking_Validation.js

@@ -0,0 +1,30 @@
+const { get_stacking_rules_input } = require('./stacking_rules_input')
+
+function resolve_stacking_source(item)
+{
+    if (typeof item.get_stacking_source_item === 'function')
+    {
+        return item.get_stacking_source_item()
+    }
+    if (typeof item.get_stacking_info === 'function')
+    {
+        return item
+    }
+    return item.get_allocation_item()
+}
+
+function create_input(item)
+{
+    return {
+        itemId: item.get_id(),
+        x: item.get_x(),
+        y: item.get_y(),
+        z: item.get_z(),
+        width: item.get_width(),
+        height: item.get_height(),
+        length: item.get_length(),
+        stackingRules: get_stacking_rules_input(resolve_stacking_source(item))
+    }
+}
+
+module.exports = create_input

package/src/Allocation_Optimization/block_builder/assert_tie_ratio_block_matches_orientation_below.js

@@ -0,0 +1,44 @@
+const No_Suitable_Item_Exception = require('./exceptions/No_Suitable_Item_Exception')
+const { ALLOCATOR_MESSAGE } = require('../../messages/Allocator_Message')
+const { build_supporters_by_top_y_index } = require('../tie_ratio/supporters_by_top_y_index')
+const { tie_ratio_orientation_below_placement } = require('../tie_ratio/tie_ratio_orientation_below_empty_space')
+
+/**
+ * Rejects tie-ratio blocks whose orientation does not match the supporter below this footprint.
+ * @param {object} container
+ * @param {{ x: number, y: number, z: number }} placement_origin
+ * @param {object} chosen_block
+ */
+function assert_tie_ratio_block_matches_orientation_below(
+    container,
+    placement_origin,
+    chosen_block
+)
+{
+    if (typeof chosen_block.is_tie_ratio_block !== 'function' || !chosen_block.is_tie_ratio_block())
+    {
+        return
+    }
+
+    const supporters_by_top_y_index = build_supporters_by_top_y_index(
+        container.get_allocated_items?.() ?? []
+    )
+    const required_orientation = tie_ratio_orientation_below_placement(
+        container,
+        placement_origin,
+        chosen_block.get_width(),
+        chosen_block.get_length(),
+        supporters_by_top_y_index
+    )
+    if (required_orientation === undefined)
+    {
+        return
+    }
+
+    if (chosen_block.get_tie_ratio_orientation() !== required_orientation)
+    {
+        throw new No_Suitable_Item_Exception(ALLOCATOR_MESSAGE.TIE_RATIO_ORIENTATION_MISMATCH)
+    }
+}
+
+module.exports = assert_tie_ratio_block_matches_orientation_below

package/src/Allocation_Optimization/block_builder/block_shape_stock.js

@@ -0,0 +1,129 @@
+const { cube_map_function } = require('../../Blocks_Preparation/Cube_Map_Function')
+
+/**
+ * @param {object} block
+ * @returns {Map<string, number>}
+ */
+function build_required_shape_amounts(block)
+{
+    const required_shapes = new Map()
+    for (const slot of block.get_slot_list())
+    {
+        const shape_hash = cube_map_function(slot)
+        required_shapes.set(shape_hash, (required_shapes.get(shape_hash) || 0) + 1)
+    }
+    return required_shapes
+}
+
+/**
+ * Counts each item's amount once per unique rotation shape (no rotation inflation).
+ * @param {object} item_map - id → item
+ * @param {object} item_amount_map - controller with get_item_amount(item)
+ * @returns {Map<string, number>}
+ */
+function build_available_shape_amounts(item_map, item_amount_map)
+{
+    const available_shapes = new Map()
+    for (const item_id of Object.keys(item_map))
+    {
+        const item = item_map[item_id]
+        const amount = item_amount_map.get_item_amount(item)
+        if (amount <= 0)
+        {
+            continue
+        }
+        const unique_hashes = new Set()
+        for (const rotated_item of item.get_all_rotated_options())
+        {
+            unique_hashes.add(cube_map_function(rotated_item))
+        }
+        for (const shape_hash of unique_hashes)
+        {
+            available_shapes.set(shape_hash, (available_shapes.get(shape_hash) || 0) + amount)
+        }
+    }
+    return available_shapes
+}
+
+/**
+ * True when stock can cover the block: total capable units ≥ slot count, and each shape
+ * has enough under unique-rotation counting (same rule as Insuficient_Items_Filter).
+ * @param {object} block
+ * @param {object} item_map
+ * @param {object} item_amount_map
+ * @returns {boolean}
+ */
+function block_has_sufficient_shape_stock(block, item_map, item_amount_map)
+{
+    const required_shapes = build_required_shape_amounts(block)
+    if (required_shapes.size === 0)
+    {
+        return false
+    }
+    let total_required = 0
+    for (const required_amount of required_shapes.values())
+    {
+        total_required += required_amount
+    }
+    if (count_capable_item_amount(required_shapes, item_map, item_amount_map) < total_required)
+    {
+        return false
+    }
+    const available_shapes = build_available_shape_amounts(item_map, item_amount_map)
+    for (const [shape_hash, required_amount] of required_shapes)
+    {
+        if ((available_shapes.get(shape_hash) || 0) < required_amount)
+        {
+            return false
+        }
+    }
+    return true
+}
+
+/**
+ * @param {Map<string, number>} required_shapes
+ * @param {object} item_map
+ * @param {object} item_amount_map
+ * @returns {number}
+ */
+function count_capable_item_amount(required_shapes, item_map, item_amount_map)
+{
+    let capable_amount = 0
+    for (const item_id of Object.keys(item_map))
+    {
+        const item = item_map[item_id]
+        const amount = item_amount_map.get_item_amount(item)
+        if (amount <= 0)
+        {
+            continue
+        }
+        if (item_can_form_any_required_shape(item, required_shapes))
+        {
+            capable_amount += amount
+        }
+    }
+    return capable_amount
+}
+
+/**
+ * @param {object} item
+ * @param {Map<string, number>} required_shapes
+ * @returns {boolean}
+ */
+function item_can_form_any_required_shape(item, required_shapes)
+{
+    for (const rotated_item of item.get_all_rotated_options())
+    {
+        if (required_shapes.has(cube_map_function(rotated_item)))
+        {
+            return true
+        }
+    }
+    return false
+}
+
+module.exports = {
+    block_has_sufficient_shape_stock,
+    build_required_shape_amounts,
+    build_available_shape_amounts
+}

package/src/Allocation_Optimization/block_builder/exceptions/Empty_Block_Item_List_Exception.js

@@ -0,0 +1,21 @@
+const { build_message_entry } = require('../../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../../messages/Allocator_Message')
+
+class Empty_Block_Item_List_Exception extends Error
+{
+    /**
+     * @param {string|number} block_id
+     * @param {number} slot_count
+     */
+    constructor(block_id, slot_count)
+    {
+        const message_key = ALLOCATOR_MESSAGE.EMPTY_BLOCK_ITEM_LIST
+        super(message_key)
+        this.message_entry = build_message_entry(
+            message_key,
+            [String(block_id), String(slot_count)]
+        )
+    }
+}
+
+module.exports = Empty_Block_Item_List_Exception

package/src/Allocation_Optimization/block_builder/exceptions/Invalid_Stacking_Exception.js

@@ -0,0 +1,14 @@
+const { build_message_entry } = require('../../../messages/resolve_error_message_entry')
+const { ALLOCATOR_MESSAGE } = require('../../../messages/Allocator_Message')
+
+class Invalid_Stacking_Exception extends Error
+{
+    constructor()
+    {
+        const message_key = ALLOCATOR_MESSAGE.INVALID_STACKING
+        super(message_key)
+        this.message_entry = build_message_entry(message_key)
+    }
+}
+
+module.exports = Invalid_Stacking_Exception

package/src/Allocation_Optimization/block_builder/exceptions/No_Suitable_Item_Exception.js

@@ -0,0 +1,16 @@
+const { build_message_entry } = require('../../../messages/resolve_error_message_entry')
+
+class No_Suitable_Item_Exception extends Error
+{
+    /**
+     * @param {string} message_key
+     * @param {string[]} [params=[]]
+     */
+    constructor(message_key, params = [])
+    {
+        super(message_key)
+        this.message_entry = build_message_entry(message_key, params)
+    }
+}
+
+module.exports = No_Suitable_Item_Exception