@jetta/blocks-allocator 0.0.0-stage → 0.1.0-0

package/src/Allocation_Optimization/item_consumption_heuristic/exceptions/No_Slots_For_Items_Exception.js

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

package/src/Allocation_Optimization/lp_model/Block_Weight_Calculator.js

@@ -0,0 +1,31 @@
+const Cargo_Profile = require('../../models/Cargo_Profile')
+const Measure_Reader = require('../functions/Measure_Reader')
+const measure_to_optimize = require('../functions/measure_to_optimize')
+const get_custom_weight = require('../functions/Weight_Getter/Variable_Weight_Getter')
+
+function get_measure(obj)
+{
+    switch (Measure_Reader.read_measure_to_be_optimized())
+    {
+        case measure_to_optimize.LENGTH:
+            return obj.length !== undefined ? obj.length : obj.get_length()
+        case measure_to_optimize.WIDTH:
+            return obj.width !== undefined ? obj.width : obj.get_width()
+        default:
+            throw new Error('invalid measure identifier')
+    }
+}
+
+function buff_block(block)
+{
+    return Cargo_Profile.enable_blocks_extra_score() ? (1 + (block.is_block() ? 1 : 0)) / 1.5 : 1
+}
+
+module.exports = function calculate_block_var_weight(block)
+{
+    const measure = Number(get_measure(block))
+    const custom_additional_weight = get_custom_weight(block)
+    const base_weight = (measure * 10) + Number(custom_additional_weight)
+    const buff_blocks = buff_block(block)
+    return base_weight * buff_blocks
+}

package/src/Allocation_Optimization/lp_model/LP_Data_Processor.js

@@ -0,0 +1,42 @@
+
+class LP_Data_Processor
+{
+    /**
+     * Sanitizes available usable blocks based on restricted blocks.
+     * Filters out fully restricted blocks and identifies multi-slot blocks.
+     * @param {Array<Object>} available_block_list - A list of available usable block objects.
+     * @param {Object} restricted_block_map - An object mapping block IDs to their restricted status.
+     * @returns {Array<Object>} A filtered list of usable block objects, prioritizing multi-slot blocks if available.
+     */
+    sanitize(available_block_list, restricted_block_map = {})
+    {
+        const fully_restricted_ids = new Set()
+        for (const block_id of Object.keys(restricted_block_map))
+        {
+            if (restricted_block_map[block_id] == 0)
+            {
+                fully_restricted_ids.add(block_id)
+            }
+        }
+        if (fully_restricted_ids.size === 0)
+        {
+            return available_block_list
+        }
+        return available_block_list.filter(block => !fully_restricted_ids.has(block.get_id()))
+    }
+
+    /**
+     * Removes duplicate blocks from a list based on their IDs.
+     * If multiple blocks have the same ID, only the last occurrence is kept.
+     * @param {Array<Object>} blocks - A list of block objects.
+     * @returns {Array<Object>} A new list of blocks with duplicates removed.
+     */
+    remove_duplicates(blocks)
+    {
+        const map = {}
+        blocks.forEach(block => map[block.get_id()] = block)
+        return Object.values(map)
+    }
+}
+
+module.exports = LP_Data_Processor

package/src/Allocation_Optimization/lp_model/LP_Item_Slot_Assignment.js

@@ -0,0 +1,93 @@
+const round = require('../../tools/Rounder')
+
+/**
+ * Builds per-block-instance item id queues from LP block_item_amount variables.
+ * @param {object} result - Optimizer result with variables().
+ * @param {{ slot_demand_list: object[] }} item_assignment_context
+ * @returns {Map<string, string[]>} block_id -> ordered item ids (one per block instance)
+ */
+function build_block_instance_item_queues(result, item_assignment_context)
+{
+    const variable_values = index_variable_values(result)
+    const queues = new Map()
+
+    for (const slot_demand of item_assignment_context.slot_demand_list)
+    {
+        merge_slot_demand_into_queues(slot_demand, variable_values, queues)
+    }
+
+    return queues
+}
+
+function index_variable_values(result)
+{
+    const values = new Map()
+
+    for (const variable of result.variables())
+    {
+        if (!variable.name.startsWith('block_item_amount_'))
+        {
+            continue
+        }
+
+        const amount = round(variable.value)
+        if (amount > 0)
+        {
+            values.set(variable.name, amount)
+        }
+    }
+
+    return values
+}
+
+function merge_slot_demand_into_queues(slot_demand, variable_values, queues)
+{
+    const { block_id, required_amount, compatibility_list } = slot_demand
+    const item_ids_for_slot_shape = expand_item_counts(compatibility_list, variable_values)
+
+    if (item_ids_for_slot_shape.length === 0)
+    {
+        return
+    }
+
+    if (required_amount !== 1)
+    {
+        return
+    }
+
+    const block_instances = item_ids_for_slot_shape.length
+    if (!queues.has(block_id))
+    {
+        queues.set(block_id, new Array(block_instances))
+    }
+
+    const block_queue = queues.get(block_id)
+    for (let index = 0; index < block_instances; index++)
+    {
+        if (!block_queue[index])
+        {
+            block_queue[index] = []
+        }
+        block_queue[index].push(item_ids_for_slot_shape[index])
+    }
+}
+
+function expand_item_counts(compatibility_list, variable_values)
+{
+    const item_ids = []
+
+    for (const entry of compatibility_list)
+    {
+        const count = variable_values.get(entry.variable_name) || 0
+        for (let index = 0; index < count; index++)
+        {
+            item_ids.push(entry.item_id)
+        }
+    }
+
+    return item_ids
+}
+
+module.exports = {
+    build_block_instance_item_queues
+}

package/src/Allocation_Optimization/lp_model/LP_Result_Mapper.js

@@ -0,0 +1,47 @@
+
+const round = require('../../tools/Rounder')
+const { read_measure_to_be_optimized } = require('../functions/Measure_Reader')
+const { build_block_instance_item_queues } = require('./LP_Item_Slot_Assignment')
+
+class LP_Result_Mapper
+{
+    constructor(block_map)
+    {
+        this.block_map = block_map
+    }
+
+    map_result(result, item_assignment_context = null)
+    {
+        const allocated_blocks = {
+            optimized_measure: read_measure_to_be_optimized(),
+            chosen_blocks: [],
+            block_instance_item_queues: new Map()
+        }
+
+        for (const variable of result.variables())
+        {
+            const is_block_var = (variable) => this.block_map[variable.name]
+            if (is_block_var(variable))
+            {
+                const block_object = this.block_map[variable.name]
+                const chosen_block = { block: block_object, amount: round(variable.value) }
+                if (chosen_block.amount > 0)
+                {
+                    allocated_blocks.chosen_blocks.push(chosen_block)
+                }
+            }
+        }
+
+        if (item_assignment_context)
+        {
+            allocated_blocks.block_instance_item_queues = build_block_instance_item_queues(
+                result,
+                item_assignment_context
+            )
+        }
+
+        return allocated_blocks
+    }
+}
+
+module.exports = LP_Result_Mapper

package/src/Allocation_Optimization/lp_model/model_builder/Dimension_Range_Helper.js

@@ -0,0 +1,49 @@
+const Cargo_Profile = require('../../../models/Cargo_Profile')
+const { read_measure_to_be_optimized } = require('../../functions/Measure_Reader')
+const measure_to_optimize = require('../../functions/measure_to_optimize')
+
+/**
+ * Shared helpers for block dimension ranges used by the uniformity penalty and coherence restrictions.
+ * @module Dimension_Range_Helper
+ */
+
+/**
+ * Returns the perpendicular measure used for block equalization (width when optimizing length, length when optimizing width).
+ * @param {object} obj - Object with width/length or get_width/get_length.
+ * @returns {number} The penalty measure value.
+ */
+function get_penalty_measure(obj)
+{
+    switch (read_measure_to_be_optimized())
+    {
+        case measure_to_optimize.LENGTH:
+            return obj.width !== undefined ? obj.width : obj.get_width()
+        case measure_to_optimize.WIDTH:
+            return obj.length !== undefined ? obj.length : obj.get_length()
+        default:
+            throw new Error('invalid measure identifier')
+    }
+}
+
+/**
+ * Returns the dimension range id for a block, used for uniformity penalty and coherence restrictions.
+ * @param {object} block - The block object.
+ * @returns {number} The range id (same as used in penalty variable names).
+ */
+function get_dimension_range(block)
+{
+    const tolerance = Cargo_Profile.block_equalization_tolerance()
+    if (tolerance <= 0)
+    {
+        return get_penalty_measure(block)
+    }
+
+    const penalty_measure = get_penalty_measure(block)
+    const range_id = Math.ceil(penalty_measure / tolerance) * tolerance
+    return range_id
+}
+
+module.exports = {
+    get_penalty_measure,
+    get_dimension_range
+}

package/src/Allocation_Optimization/lp_model/model_builder/Item_Assignment_Variables.js

@@ -0,0 +1,133 @@
+const create_hash = require('../../../tools/Hash')
+const {
+    get_dimension_hash,
+    collect_rotation_dimension_hashes
+} = require('./item_dimension_hashes')
+const Missing_Item_Stock_Exception = require('./exceptions/Missing_Item_Stock_Exception')
+
+/**
+ * Builds the LP assignment graph between blocks, slot shapes, and compatible items.
+ * Single source of truth for the `block_item_amount_<hash>` variable naming used by
+ * Block_Item_Amount_Restriction and Single_Item_Type_Restriction.
+ * @param {object[]} block_list - Block objects (must expose get_id and get_slot_list).
+ * @param {object[]} item_list - Item objects (must expose get_id, get_amount and get_all_rotated_options).
+ * @returns {{
+ *     slot_demand_list: Array<{block_id: string, slot_hash: string, required_amount: number, compatibility_list: Array<{item_id: string, variable_name: string}>}>,
+ *     variables_by_item: Map<string, string[]>,
+ *     id_to_stock_map: Map<string, number>
+ * }}
+ */
+function create_item_assignment_variables(block_list, item_list)
+{
+    const { dim_to_id_map, id_to_stock_map } = build_item_dimension_and_stock_maps(item_list)
+    const slot_demand_list = build_block_slot_demand_list(block_list, dim_to_id_map)
+    const variables_by_item = group_variable_names_by_item(slot_demand_list)
+    return { slot_demand_list, variables_by_item, id_to_stock_map }
+}
+
+/**
+ * Reads stock for an item id from the map built with create_item_assignment_variables.
+ * @param {Map<string, number>} id_to_stock_map - Item id to available amount.
+ * @param {string} item_id - Item id to resolve.
+ * @returns {number} Stock amount for the item.
+ * @throws {Missing_Item_Stock_Exception} When the item id is missing from the map.
+ */
+function read_stock(id_to_stock_map, item_id)
+{
+    const amount = id_to_stock_map.get(item_id)
+    if (amount === undefined)
+    {
+        throw new Missing_Item_Stock_Exception(item_id)
+    }
+    return amount
+}
+
+module.exports = create_item_assignment_variables
+module.exports.read_stock = read_stock
+
+function build_item_dimension_and_stock_maps(item_list)
+{
+    const dim_to_id_map = new Map()
+    const id_to_stock_map = new Map()
+    for (const item of item_list)
+    {
+        const item_id = item.get_id()
+        index_item_rotations(dim_to_id_map, item)
+        if (!id_to_stock_map.has(item_id))
+        {
+            id_to_stock_map.set(item_id, item.get_amount())
+        }
+    }
+    return { dim_to_id_map, id_to_stock_map }
+}
+
+function index_item_rotations(dim_to_id_map, item)
+{
+    const item_id = item.get_id()
+    for (const hash of collect_rotation_dimension_hashes(item))
+    {
+        if (!dim_to_id_map.has(hash))
+        {
+            dim_to_id_map.set(hash, new Set())
+        }
+        dim_to_id_map.get(hash).add(item_id)
+    }
+}
+
+function build_block_slot_demand_list(block_list, dim_to_id_map)
+{
+    const slot_demand_list = []
+    for (const block of block_list)
+    {
+        const block_id = block.get_id()
+        const demand_by_slot_hash = get_block_slot_demand(block)
+        for (const [slot_hash, required_amount] of demand_by_slot_hash.entries())
+        {
+            slot_demand_list.push({
+                block_id,
+                slot_hash,
+                required_amount,
+                compatibility_list: build_compatibility_list(block_id, slot_hash, dim_to_id_map)
+            })
+        }
+    }
+    return slot_demand_list
+}
+
+function get_block_slot_demand(block)
+{
+    const demand_by_slot_hash = new Map()
+    for (const slot of block.get_slot_list())
+    {
+        const slot_hash = get_dimension_hash(slot)
+        const current_count = demand_by_slot_hash.get(slot_hash) || 0
+        demand_by_slot_hash.set(slot_hash, current_count + 1)
+    }
+    return demand_by_slot_hash
+}
+
+function build_compatibility_list(block_id, slot_hash, dim_to_id_map)
+{
+    const compatible_id_set = dim_to_id_map.get(slot_hash) || new Set()
+    return [...compatible_id_set].map(item_id => ({
+        item_id,
+        variable_name: `block_item_amount_${create_hash(`${block_id};${slot_hash};${item_id}`)}`
+    }))
+}
+
+function group_variable_names_by_item(slot_demand_list)
+{
+    const variables_by_item = new Map()
+    for (const slot_demand of slot_demand_list)
+    {
+        for (const entry of slot_demand.compatibility_list)
+        {
+            if (!variables_by_item.has(entry.item_id))
+            {
+                variables_by_item.set(entry.item_id, [])
+            }
+            variables_by_item.get(entry.item_id).push(entry.variable_name)
+        }
+    }
+    return variables_by_item
+}

package/src/Allocation_Optimization/lp_model/model_builder/LP_Model_Builder.js

@@ -0,0 +1,132 @@
+const create_coherence_restrictions = require('./restrictions/Coherence_Restriction')
+const create_item_assignment_variables = require('./Item_Assignment_Variables')
+const create_block_item_amount_restriction = require('./restrictions/Block_Item_Amount_Restriction')
+const create_container_supported_weight_restriction = require('./restrictions/Container_Supported_Weight_Restriction')
+const create_block_restricted_to_0_restriction = require('./restrictions/Unavailable_Block_Restriction')
+const create_single_item_type_restriction = require('./restrictions/Single_Item_Type_Restriction')
+const create_uniform_block_measure_restriction = require('./restrictions/Uniform_Block_Measure_Restriction')
+const create_relational_group_restriction = require('./restrictions/Relational_Group_Restriction')
+const create_relational_exact_pass_amount_restriction = require('./restrictions/Relational_Exact_Pass_Amount_Restriction')
+const create_space_restriction = require('./restrictions/Space_Restriction')
+const Goal_Function_Creator = require('./goal_function/Goal_Function_Creator')
+
+function validate_data(data)
+{
+    if (data == null || typeof data !== 'object')
+    {
+        throw new Error('LP_Model_Builder: data is required and must be an object')
+    }
+    const required = ['optimizer', 'container', 'empty_space', 'block_list', 'item_list']
+    for (const key of required)
+    {
+        if (data[key] === undefined)
+        {
+            throw new Error(`LP_Model_Builder: data.${key} is required`)
+        }
+    }
+    if (!Array.isArray(data.block_list) || !Array.isArray(data.item_list))
+    {
+        throw new Error('LP_Model_Builder: data.block_list and data.item_list must be arrays')
+    }
+}
+
+/**
+ * Assembles the full LP model: goal function and all restrictions (space, block-item, container weight,
+ * coherence, unavailable blocks, and single-item-type caps where applicable).
+ */
+class LP_Model_Builder
+{
+    #goal_function
+    #optimizer
+    #container
+    #empty_space
+    #block_list
+    #item_list
+    #block_amount_map
+    #enable_uniformity_penalty
+    #item_assignment_context = null
+
+    /**
+     * @param {object} data - Builder configuration.
+     * @param {object} data.optimizer - LP optimizer instance to receive goal and restrictions.
+     * @param {object} data.container - Container (e.g. supported_weight).
+     * @param {object} data.empty_space - Space to allocate (measure used for space restriction).
+     * @param {Array<object>} data.block_list - Available blocks.
+     * @param {Array<object>} data.item_list - Items for block-item constraints.
+     * @param {object} data.block_amount_map - Map of block id to max amount (unavailable-block restrictions).
+     * @param {boolean} [data.enable_uniformity_penalty=true] - Whether to add uniformity penalty in the goal.
+     */
+    constructor(data)
+    {
+        validate_data(data)
+        const {
+            optimizer,
+            container,
+            empty_space,
+            block_list,
+            item_list,
+            block_amount_map,
+            enable_uniformity_penalty = true
+        } = data
+        this.#optimizer = optimizer
+        this.#container = container
+        this.#empty_space = empty_space
+        this.#block_list = block_list
+        this.#item_list = item_list
+        this.#block_amount_map = block_amount_map
+        this.#enable_uniformity_penalty = enable_uniformity_penalty
+    }
+
+    /**
+     * Builds the LP model: goal function and all restrictions, and registers them with the optimizer.
+     * @returns {void}
+     */
+    build_model()
+    {
+        const penalty_vars = this.#build_goal_function()
+        this.#optimizer.set_goal_function(this.#goal_function)
+        this.#build_restrictions(penalty_vars)
+    }
+
+    /**
+     * Returns the item assignment context built during the last build_model() call.
+     * @returns {{slot_demand_list: Array, variables_by_item: Map<string, string[]>, id_to_stock_map: Map<string, number>}|null}
+     */
+    get_item_assignment_context()
+    {
+        return this.#item_assignment_context
+    }
+
+    #build_goal_function()
+    {
+        const goal_function_creator         = new Goal_Function_Creator(this.#block_list, this.#enable_uniformity_penalty)
+        const {goal_function, penalty_vars} = goal_function_creator.create_goal_function()
+        this.#goal_function = goal_function
+        return penalty_vars
+    }
+
+    #build_restrictions(penalty_var_list)
+    {
+        this.#item_assignment_context = create_item_assignment_variables(this.#block_list, this.#item_list)
+        const restriction_list = [
+            ...create_space_restriction(this.#empty_space, this.#block_list),
+            ...create_block_item_amount_restriction(this.#block_list, this.#item_list, this.#item_assignment_context),
+            ...create_container_supported_weight_restriction(this.#container, this.#block_list, this.#item_list),
+            ...create_coherence_restrictions(penalty_var_list, this.#block_list),
+            ...create_uniform_block_measure_restriction(this.#block_list, this.#item_list),
+            ...create_block_restricted_to_0_restriction(this.#block_list, this.#block_amount_map ?? {}),
+            ...create_single_item_type_restriction(this.#block_list, this.#item_list, this.#item_assignment_context),
+            ...create_relational_group_restriction(this.#block_list, this.#item_list, this.#item_assignment_context),
+            ...create_relational_exact_pass_amount_restriction(this.#block_list, this.#item_list, this.#item_assignment_context)
+        ]
+
+        this.#add_restriction_list(restriction_list)
+    }
+
+    #add_restriction_list(restriction_list)
+    {
+        restriction_list.forEach(restriction => this.#optimizer.add_restriction(restriction))
+    }
+}
+
+module.exports = LP_Model_Builder

package/src/Allocation_Optimization/lp_model/model_builder/exceptions/Missing_Item_Stock_Exception.js

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

package/src/Allocation_Optimization/lp_model/model_builder/goal_function/Goal_Function_Creator.js

@@ -0,0 +1,83 @@
+const {
+    GoalFunction,
+    OptimizationCriteria,
+    VariableType,
+    create_variable
+} = require('@jetta/lp-framework')
+const Cargo_Profile = require('../../../../models/Cargo_Profile')
+const { get_dimension_range } = require('../Dimension_Range_Helper')
+const calculate_block_var_weight = require('../../Block_Weight_Calculator')
+
+/**
+ * Builds the LP goal function (objective) and optional uniformity penalty variables for block equalization.
+ */
+module.exports = class Goal_Function_Creator
+{
+    #goal_function
+    #block_list
+    #enable_uniformity_penalty
+    #penalty_vars = []
+    /**
+     * @param {Array<object>} block_list - List of blocks; each must have get_id().
+     * @param {boolean} enable_uniformity_penalty - Whether to add uniformity penalty variables when equalization is enabled.
+     */
+    constructor(block_list, enable_uniformity_penalty)
+    {
+        this.#block_list = block_list
+        this.#enable_uniformity_penalty = enable_uniformity_penalty
+        this.#goal_function = new GoalFunction(OptimizationCriteria.MAX)
+    }
+
+    /**
+     * Builds the goal function with block variables and, when enabled, uniformity penalty variables.
+     * @returns {{ goal_function: import('@jetta/lp-framework').GoalFunction, penalty_vars: Array<object> }} The goal function and list of penalty variables for coherence restrictions.
+     */
+    create_goal_function()
+    {
+        this.#add_block_variables_to_goal(this.#block_list)
+        const enabled = Cargo_Profile.enable_block_equalization()
+        if (enabled && this.#enable_uniformity_penalty)
+        {
+            this.#add_uniformity_penalty_to_goal()
+        }
+
+        return {
+            goal_function: this.#goal_function,
+            penalty_vars: this.#penalty_vars
+        }
+    }
+
+    #add_block_variables_to_goal(block_list)
+    {
+        for (const block of block_list)
+        {
+            const var_name = block.get_id()
+            const weight = calculate_block_var_weight(block)
+            const variable = create_variable(var_name, weight, VariableType.INTEGER)
+            this.#goal_function.set_variable(variable)
+        }
+    }
+
+    #add_uniformity_penalty_to_goal()
+    {
+        const unique_ranges = [...new Set(this.#block_list.map(b => get_dimension_range(b)))]
+
+        for (const range_id of unique_ranges)
+        {
+            const penalty_var_name = `used_penalty_range_${range_id}`
+            const penalty_variable = this.#create_penalty_variable(penalty_var_name)
+            this.#goal_function.set_variable(penalty_variable)
+            this.#penalty_vars.push(penalty_variable)
+        }
+    }
+
+    #create_penalty_variable(name)
+    {
+        const penalty_coefficient = parseInt(Cargo_Profile.block_equalization_penalty_coefficient())
+        const penalty_variable = create_variable(name, penalty_coefficient, VariableType.INTEGER)
+        return penalty_variable
+    }
+}
+
+
+

package/src/Allocation_Optimization/lp_model/model_builder/item_dimension_hashes.js

@@ -0,0 +1,31 @@
+/**
+ * Builds the same dimension string key used across LP restrictions (width;height;length).
+ * @param {object} cube - Object with get_width, get_height, and get_length methods.
+ * @returns {string} Semicolon-separated dimensions.
+ */
+function get_dimension_hash(cube)
+{
+    return `${cube.get_width()};${cube.get_height()};${cube.get_length()}`
+}
+
+/**
+ * Collects dimension hashes for every rotation of an item (matches Block_Item indexing).
+ * @param {object} item - Item with get_all_rotated_options().
+ * @returns {Set<string>} Unique dimension hashes for all rotated orientations.
+ */
+function collect_rotation_dimension_hashes(item)
+{
+    const hash_set = new Set()
+
+    for (const rotated_item of item.get_all_rotated_options())
+    {
+        hash_set.add(get_dimension_hash(rotated_item))
+    }
+
+    return hash_set
+}
+
+module.exports = {
+    get_dimension_hash,
+    collect_rotation_dimension_hashes
+}