@jetta/blocks-allocator 0.0.0-stage → 0.1.0

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Block_Item_Amount_Restriction.js

@@ -0,0 +1,53 @@
+const create_hash = require('../../../../tools/Hash')
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+const create_item_assignment_variables = require('../Item_Assignment_Variables')
+const read_stock = create_item_assignment_variables.read_stock
+
+/**
+ * Creates restrictions that assign compatible item stock to block slot shapes
+ * while respecting item availability.
+ * @param {object[]} block_list - An array of Block objects.
+ * @param {object[]} item_list - An array of Item objects.
+ * @param {{slot_demand_list: Array, variables_by_item: Map<string, string[]>, id_to_stock_map: Map<string, number>}} [item_assignment_context] - Precomputed
+ *     assignment graph from create_item_assignment_variables; when omitted, it is computed from block_list and item_list.
+ * @returns {Restriction[]} An array of LP restrictions.
+ */
+module.exports = function create_block_item_amount_restriction(block_list, item_list, item_assignment_context)
+{
+    const bundle = item_assignment_context ?? create_item_assignment_variables(block_list, item_list)
+    const { slot_demand_list, variables_by_item, id_to_stock_map } = bundle
+    const restriction_list = []
+    for (const slot_demand of slot_demand_list)
+    {
+        restriction_list.push(build_slot_demand_restriction(slot_demand))
+    }
+    restriction_list.push(...build_item_stock_restrictions(variables_by_item, id_to_stock_map))
+    return restriction_list
+}
+
+function build_slot_demand_restriction(slot_demand)
+{
+    const { block_id, slot_hash, required_amount, compatibility_list } = slot_demand
+    const name = `block_item_demand_${create_hash(`${block_id};${slot_hash}`)}`
+    const variable_list = compatibility_list.map(
+        entry => create_variable(entry.variable_name, 1, VariableType.INTEGER)
+    )
+    variable_list.push(create_variable(block_id, -required_amount, VariableType.INTEGER))
+    return create_restriction(name, variable_list, {lower_limit: 0, upper_limit: 0})
+}
+
+function build_item_stock_restrictions(variables_by_item, id_to_stock_map)
+{
+    const restriction_list = []
+    let count = 0
+    for (const [item_id, variable_name_list] of variables_by_item.entries())
+    {
+        const total_stock = read_stock(id_to_stock_map, item_id)
+        const variable_list = variable_name_list.map(
+            name => create_variable(name, 1, VariableType.INTEGER)
+        )
+        const name = `max_item_per_block_${item_id}-${++count}`
+        restriction_list.push(create_restriction(name, variable_list, {lower_limit: 0, upper_limit: total_stock}))
+    }
+    return restriction_list
+}

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Coherence_Restriction.js

@@ -0,0 +1,65 @@
+const { VariableType, create_restriction, create_variable } = require('@jetta/lp-framework')
+const { get_dimension_range } = require('../Dimension_Range_Helper')
+
+/**
+ * Builds LP restrictions that tie penalty variables to block usage per dimension range (for uniformity penalty).
+ * @param {Array<{ name: string }>} penalty_var_list - List of penalty variables (names like "used_penalty_range_<range_id>").
+ * @param {Array<object>} block_list - List of blocks; each must have get_id() and match get_dimension_range() for filtering.
+ * @returns {Array<import('@jetta/lp-framework').Restriction>} List of coherence restrictions (binary check, upper, and lower per range).
+ */
+function create_coherence_restrictions(penalty_var_list, block_list)
+{
+    const size = penalty_var_list.length
+    const restriction_list = []
+
+    for (let index = 0; index < size; index++)
+    {
+        const penalty_var = penalty_var_list[index]
+        const var_name = penalty_var.name
+        const splitted_var_name = var_name.split('_')
+        const range_id = Number(splitted_var_name[splitted_var_name.length - 1])
+        if (Number.isNaN(range_id))
+        {
+            continue
+        }
+        const blocks_in_range = block_list.filter(block => get_dimension_range(block) === range_id)
+        const sum_block_vars = blocks_in_range.map(block => create_variable(block.get_id(), 1, VariableType.INTEGER))
+        const variable = create_variable(var_name, 1, VariableType.INTEGER)
+        const name = `binary_check_${var_name}`
+        const restriction = create_restriction(name, [variable], {lower_limit: 0, upper_limit: 1})
+        const upper = create_upper_coherence_restriction(range_id, var_name, sum_block_vars)
+        const lower = create_lower_coherence_restriction(range_id, var_name, sum_block_vars)
+        restriction_list.push(...[upper, lower, restriction])
+    }
+
+    return restriction_list
+}
+
+module.exports = create_coherence_restrictions
+
+/**
+ * @param {number} range_id - Dimension range id.
+ * @param {string} penalty_var_name - Penalty variable name.
+ * @param {Array<object>} sum_block_vars - Variables for blocks in this range.
+ * @returns {import('@jetta/lp-framework').Restriction}
+ */
+function create_upper_coherence_restriction(range_id, penalty_var_name, sum_block_vars)
+{
+    const M = 10000
+    const variable_list = [...sum_block_vars, create_variable(penalty_var_name, -M, VariableType.INTEGER)]
+    const name = `pen_coherence_upper_${range_id}`
+    return create_restriction(name, variable_list, {lower_limit: 0, upper_limit: 0})
+}
+
+/**
+ * @param {number} range_id - Dimension range id.
+ * @param {string} penalty_var_name - Penalty variable name.
+ * @param {Array<object>} sum_block_vars - Variables for blocks in this range.
+ * @returns {import('@jetta/lp-framework').Restriction}
+ */
+function create_lower_coherence_restriction(range_id, penalty_var_name, sum_block_vars)
+{
+    const variable_list = [create_variable(penalty_var_name, 1, VariableType.INTEGER), ...sum_block_vars.map(v => create_variable(v.name, -1, VariableType.INTEGER))]
+    const name = `pen_coherence_lower_${range_id}`
+    return create_restriction(name, variable_list, {lower_limit: 0, upper_limit: 0})
+}

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Container_Supported_Weight_Restriction.js

@@ -0,0 +1,42 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+const {
+    get_dimension_to_max_weight_map,
+    calculate_block_potential_weight
+} = require('../../../Block_Potential_Weight')
+
+/**
+ * Creates a single LP restriction to ensure the total weight of items in the chosen blocks
+ * does not exceed the container's supported weight.
+ * @param {object} container - The container object, with a supported_weight() method.
+ * @param {object[]} block_list - An array of Block objects.
+ * @param {object[]} item_list - An array of Item objects.
+ * @returns {Restriction[]} An array containing the single weight restriction.
+ */
+module.exports = function create_container_supported_weight_restriction(container, block_list, item_list)
+{
+    const dimension_to_max_weight_map = get_dimension_to_max_weight_map(item_list)
+    const variable_list = []
+
+    for (const block of block_list)
+    {
+        const block_potential_weight = calculate_block_potential_weight(block, dimension_to_max_weight_map)
+
+        if (block_potential_weight > 0)
+        {
+            variable_list.push(create_variable(block.get_id(), block_potential_weight, VariableType.INTEGER))
+        }
+    }
+
+    if (variable_list.length === 0)
+    {
+        return []
+    }
+
+    const supported_weight = typeof container.supported_weight === 'function'
+        ? container.supported_weight()
+        : container.supported_weight
+
+    const name = 'container_supported_weight'
+    const restriction = create_restriction(name, variable_list, {lower_limit: 0, upper_limit: supported_weight})
+    return [restriction]
+}

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Relational_Exact_Pass_Amount_Restriction.js

@@ -0,0 +1,62 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+const Cargo_Profile = require('../../../../models/Cargo_Profile')
+const create_item_assignment_variables = require('../Item_Assignment_Variables')
+const has_relational_items = require('../../../../relational/has_relational_items')
+
+const RELATIONAL_EXACT_PASS_PREFIX = 'relational_exact_pass_amount_'
+
+/**
+ * Forces each relational item to allocate exactly its pass amount when enabled.
+ * @param {object[]} block_list
+ * @param {object[]} item_list
+ * @param {object} [item_assignment_context]
+ * @returns {Restriction[]}
+ */
+module.exports = function create_relational_exact_pass_amount_restriction(
+    block_list,
+    item_list,
+    item_assignment_context
+)
+{
+    if (!Cargo_Profile.relational_lp_require_exact_pass_amount())
+    {
+        return []
+    }
+
+    if (!has_relational_items(item_list))
+    {
+        return []
+    }
+
+    const bundle = item_assignment_context ?? create_item_assignment_variables(block_list, item_list)
+    const { variables_by_item } = bundle
+    const restriction_list = []
+
+    for (const item of item_list)
+    {
+        if (!item.get_relational_group_id())
+        {
+            continue
+        }
+
+        const variable_name_list = variables_by_item.get(item.get_id()) || []
+        if (variable_name_list.length === 0)
+        {
+            continue
+        }
+
+        const variable_list = variable_name_list.map(
+            name => create_variable(name, 1, VariableType.INTEGER)
+        )
+        const name = `${RELATIONAL_EXACT_PASS_PREFIX}${item.get_id()}`
+        const amount = item.get_amount()
+        restriction_list.push(create_restriction(name, variable_list, {
+            lower_limit: amount,
+            upper_limit: amount
+        }))
+    }
+
+    return restriction_list
+}
+
+module.exports.RELATIONAL_EXACT_PASS_PREFIX = RELATIONAL_EXACT_PASS_PREFIX

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Relational_Group_Restriction.js

@@ -0,0 +1,97 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+const Cargo_Profile = require('../../../../models/Cargo_Profile')
+const create_item_assignment_variables = require('../Item_Assignment_Variables')
+
+const RELATIONAL_GROUP_MULTIPLE_PREFIX = 'relational_group_multiple_'
+const RELATIONAL_GROUP_RATIO_PREFIX = 'relational_group_ratio_'
+
+/**
+ * Builds LP restrictions that keep each relational group on proportional integer multiples.
+ * Gated by Cargo_Profile.enforce_relational_group_co_location().
+ * @param {object[]} block_list
+ * @param {object[]} item_list
+ * @param {object} [item_assignment_context]
+ * @returns {Restriction[]}
+ */
+module.exports = function create_relational_group_restriction(block_list, item_list, item_assignment_context)
+{
+    if (!Cargo_Profile.enforce_relational_group_co_location())
+    {
+        return []
+    }
+
+    const bundle = item_assignment_context ?? create_item_assignment_variables(block_list, item_list)
+    const { variables_by_item } = bundle
+    const groups = build_relational_groups(item_list)
+
+    if (groups.size === 0)
+    {
+        return []
+    }
+
+    const restriction_list = []
+
+    for (const [group_id, group_items] of groups.entries())
+    {
+        restriction_list.push(...build_group_restrictions(group_id, group_items, variables_by_item))
+    }
+
+    return restriction_list
+}
+
+module.exports.RELATIONAL_GROUP_MULTIPLE_PREFIX = RELATIONAL_GROUP_MULTIPLE_PREFIX
+module.exports.RELATIONAL_GROUP_RATIO_PREFIX = RELATIONAL_GROUP_RATIO_PREFIX
+
+function build_relational_groups(item_list)
+{
+    const groups = new Map()
+
+    for (const item of item_list)
+    {
+        const group_id = item.get_relational_group_id()
+        if (!group_id)
+        {
+            continue
+        }
+
+        if (!groups.has(group_id))
+        {
+            groups.set(group_id, [])
+        }
+        groups.get(group_id).push(item)
+    }
+
+    return groups
+}
+
+function build_group_restrictions(group_id, group_items, variables_by_item)
+{
+    const restriction_list = []
+    const multiple_name = `${RELATIONAL_GROUP_MULTIPLE_PREFIX}${group_id}`
+    const anchor = group_items[0]
+    const anchor_vars = variables_by_item.get(anchor.get_id()) || []
+
+    if (anchor_vars.length === 0)
+    {
+        return []
+    }
+
+    for (const item of group_items)
+    {
+        const variable_name_list = variables_by_item.get(item.get_id()) || []
+        if (variable_name_list.length === 0)
+        {
+            continue
+        }
+
+        const ratio = item.get_relational_link_quantity()
+        const variable_list = variable_name_list.map(
+            name => create_variable(name, 1, VariableType.INTEGER)
+        )
+        variable_list.push(create_variable(multiple_name, -ratio, VariableType.INTEGER))
+        const name = `${RELATIONAL_GROUP_RATIO_PREFIX}${group_id}_${item.get_id()}`
+        restriction_list.push(create_restriction(name, variable_list, {lower_limit: 0, upper_limit: 0}))
+    }
+
+    return restriction_list
+}

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Single_Item_Type_Restriction.js

@@ -0,0 +1,79 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+const Cargo_Profile = require('../../../../models/Cargo_Profile')
+const create_item_assignment_variables = require('../Item_Assignment_Variables')
+const has_relational_items = require('../../../../relational/has_relational_items')
+const read_stock = create_item_assignment_variables.read_stock
+
+const SINGLE_ITEM_TYPE_INDICATOR_PREFIX = 'single_item_type_indicator_'
+const SINGLE_ITEM_TYPE_COUPLING_PREFIX = 'single_item_type_coupling_'
+const SINGLE_ITEM_TYPE_CAP_NAME = 'single_item_type_cap'
+
+/**
+ * Builds restrictions that force at most one item type to have positive count
+ * across all chosen blocks, gated by Cargo_Profile.enforce_single_item_type().
+ * Skipped when enforce_relational_group_co_location() is on and item_list
+ * contains relational_group_id items (relational bundles need multiple SKUs).
+ *
+ * For each item i: y_i in {0, 1} and sum(assignment_vars(i)) - stock_i * y_i <= 0.
+ * Globally: sum_i y_i <= 1.
+ * @param {object[]} block_list - Block objects.
+ * @param {object[]} item_list - Item objects.
+ * @param {{slot_demand_list: Array, variables_by_item: Map<string, string[]>, id_to_stock_map: Map<string, number>}} [item_assignment_context] - Precomputed
+ *     assignment graph from create_item_assignment_variables; when omitted, it is computed from block_list and item_list.
+ * @returns {Restriction[]} Empty when gated off or skipped for relational co-location; otherwise N coupling rows + 1 cap row.
+ */
+module.exports = function create_single_item_type_restriction(block_list, item_list, item_assignment_context)
+{
+    const enforce_single_item_type = Cargo_Profile.enforce_single_item_type()
+    const enforce_relational_co_location = Cargo_Profile.enforce_relational_group_co_location()
+    const relational_items_present = has_relational_items(item_list)
+    const skip_for_relational = enforce_relational_co_location && relational_items_present
+
+    if (!enforce_single_item_type || skip_for_relational)
+    {
+        return []
+    }
+    const bundle = item_assignment_context ?? create_item_assignment_variables(block_list, item_list)
+    const { variables_by_item, id_to_stock_map } = bundle
+    if (variables_by_item.size === 0)
+    {
+        return []
+    }
+    const coupling_restriction_list = build_coupling_restrictions(variables_by_item, id_to_stock_map)
+    const cap_restriction = build_cap_restriction(variables_by_item)
+    return [...coupling_restriction_list, cap_restriction]
+}
+
+module.exports.SINGLE_ITEM_TYPE_INDICATOR_PREFIX = SINGLE_ITEM_TYPE_INDICATOR_PREFIX
+module.exports.SINGLE_ITEM_TYPE_COUPLING_PREFIX = SINGLE_ITEM_TYPE_COUPLING_PREFIX
+module.exports.SINGLE_ITEM_TYPE_CAP_NAME = SINGLE_ITEM_TYPE_CAP_NAME
+
+function build_coupling_restrictions(variables_by_item, id_to_stock_map)
+{
+    const restriction_list = []
+    for (const [item_id, variable_name_list] of variables_by_item.entries())
+    {
+        const stock = read_stock(id_to_stock_map, item_id)
+        restriction_list.push(build_coupling_restriction(item_id, variable_name_list, stock))
+    }
+    return restriction_list
+}
+
+function build_coupling_restriction(item_id, variable_name_list, stock)
+{
+    const indicator_name = `${SINGLE_ITEM_TYPE_INDICATOR_PREFIX}${item_id}`
+    const variable_list = variable_name_list.map(
+        name => create_variable(name, 1, VariableType.INTEGER)
+    )
+    variable_list.push(create_variable(indicator_name, -stock, VariableType.INTEGER))
+    const name = `${SINGLE_ITEM_TYPE_COUPLING_PREFIX}${item_id}`
+    return create_restriction(name, variable_list, {lower_limit: -stock, upper_limit: 0})
+}
+
+function build_cap_restriction(variables_by_item)
+{
+    const variable_list = [...variables_by_item.keys()].map(item_id =>
+        create_variable(`${SINGLE_ITEM_TYPE_INDICATOR_PREFIX}${item_id}`, 1, VariableType.INTEGER)
+    )
+    return create_restriction(SINGLE_ITEM_TYPE_CAP_NAME, variable_list, {lower_limit: 0, upper_limit: 1})
+}

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Space_Restriction.js

@@ -0,0 +1,47 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+
+const measure_to_optimize = require('../../../functions/measure_to_optimize')
+const { read_measure_to_be_optimized } = require('../../../functions/Measure_Reader')
+
+/**
+ * Builds the space restriction: sum of block measures (by optimization dimension) must not exceed the given space.
+ * @param {object} empty_space - Space to allocate; must have length/width or get_length/get_width per measure config.
+ * @param {Array<object>} block_list - Blocks; each must have get_id() and the measure used by the optimizer.
+ * @returns {Array<import('@jetta/lp-framework').Restriction>} A single-element array containing the space restriction.
+ */
+function create_space_restriction(empty_space, block_list)
+{
+    const variable_list = create_variable_list(block_list)
+    const space_measure = get_measure(empty_space)
+    const name = 'space_restriction'
+    const restriction = create_restriction(name, variable_list, {lower_limit: 0, upper_limit: space_measure})
+    return [restriction]
+}
+
+module.exports = create_space_restriction
+
+function create_variable_list(block_list)
+{
+    return block_list.map(block =>
+    {
+        const measure = get_measure(block)
+        return create_variable(block.get_id(), measure, VariableType.INTEGER)
+    })
+}
+
+/**
+ * @param {object} obj - Object with length/width or get_length/get_width.
+ * @returns {number} Measure value for the current optimization dimension.
+ */
+function get_measure(obj)
+{
+    switch (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')
+    }
+}

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Unavailable_Block_Restriction.js

@@ -0,0 +1,27 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+
+/**
+ * Builds restrictions that cap the number of times each block can be used when it has an explicit max amount.
+ * @param {Array<object>} block_list - Blocks; each must have get_id().
+ * @param {object} block_amount_restrictions - Map of block id to maximum allowed amount (upper bound).
+ * @returns {Array<import('@jetta/lp-framework').Restriction>} One restriction per block that has an entry in block_amount_restrictions.
+ */
+function create_block_restricted_to_0_restriction(block_list, block_amount_restrictions)
+{
+    const restriction_list = []
+    for (const block of block_list)
+    {
+        const restrict_to = block_amount_restrictions[block.get_id()]
+        if (restrict_to !== undefined)
+        {
+            const variable = create_variable(block.get_id(), 1, VariableType.INTEGER)
+            const name = `block ${block.get_id()} is restricted to ${restrict_to}`
+            const restriction = create_restriction( name, [variable], {lower_limit: 0, upper_limit: restrict_to})
+            restriction_list.push(restriction)
+        }
+    }
+
+    return restriction_list
+}
+
+module.exports = create_block_restricted_to_0_restriction

package/src/Allocation_Optimization/lp_model/model_builder/restrictions/Uniform_Block_Measure_Restriction.js

@@ -0,0 +1,92 @@
+const { VariableType, create_variable, create_restriction } = require('@jetta/lp-framework')
+const Cargo_Profile = require('../../../../models/Cargo_Profile')
+const { get_dimension_range } = require('../Dimension_Range_Helper')
+const has_relational_items = require('../../../../relational/has_relational_items')
+
+const UNIFORM_BLOCK_MEASURE_INDICATOR_PREFIX = 'uniform_block_measure_indicator_'
+const UNIFORM_BLOCK_MEASURE_COUPLING_PREFIX = 'uniform_block_measure_coupling_'
+const UNIFORM_BLOCK_MEASURE_CAP_NAME = 'uniform_block_measure_cap'
+const BIG_M = 10000
+
+/**
+ * Builds restrictions that force at most one orthogonal-dimension bucket across chosen blocks,
+ * gated by Cargo_Profile.enforce_uniform_block_measure().
+ * Skipped when relational co-location is enforced and relational items are present
+ * (same skip pattern as single-item-type), because ratio groups need differently sized
+ * unitary blocks in one wall.
+ *
+ * For each range r: sum(x_b for b in range) - M * y_r <= 0.
+ * Globally: sum_r y_r <= 1.
+ * @param {object[]} block_list - Block objects.
+ * @param {object[]} [item_list=[]] - Items for the relational skip check.
+ * @returns {import('@jetta/lp-framework').Restriction[]} Empty when the flag is off or skipped.
+ */
+module.exports = function create_uniform_block_measure_restriction(block_list, item_list = [])
+{
+    const enforce_uniform = Cargo_Profile.enforce_uniform_block_measure()
+    const enforce_relational_co_location = Cargo_Profile.enforce_relational_group_co_location()
+    const skip_for_relational = enforce_relational_co_location && has_relational_items(item_list)
+
+    if (!enforce_uniform || skip_for_relational)
+    {
+        return []
+    }
+    const blocks_by_range = group_blocks_by_dimension_range(block_list)
+    if (blocks_by_range.size === 0)
+    {
+        return []
+    }
+    const coupling_restriction_list = build_coupling_restrictions(blocks_by_range)
+    const cap_restriction = build_cap_restriction(blocks_by_range)
+    return [...coupling_restriction_list, cap_restriction]
+}
+
+module.exports.UNIFORM_BLOCK_MEASURE_INDICATOR_PREFIX = UNIFORM_BLOCK_MEASURE_INDICATOR_PREFIX
+module.exports.UNIFORM_BLOCK_MEASURE_COUPLING_PREFIX = UNIFORM_BLOCK_MEASURE_COUPLING_PREFIX
+module.exports.UNIFORM_BLOCK_MEASURE_CAP_NAME = UNIFORM_BLOCK_MEASURE_CAP_NAME
+
+function group_blocks_by_dimension_range(block_list)
+{
+    const blocks_by_range = new Map()
+    for (const block of block_list)
+    {
+        const range_id = get_dimension_range(block)
+        const blocks_in_range = blocks_by_range.get(range_id) ?? []
+        blocks_in_range.push(block)
+        blocks_by_range.set(range_id, blocks_in_range)
+    }
+    return blocks_by_range
+}
+
+function build_coupling_restrictions(blocks_by_range)
+{
+    const restriction_list = []
+    for (const [range_id, blocks_in_range] of blocks_by_range.entries())
+    {
+        restriction_list.push(build_coupling_restriction(range_id, blocks_in_range))
+    }
+    return restriction_list
+}
+
+function build_coupling_restriction(range_id, blocks_in_range)
+{
+    const indicator_name = `${UNIFORM_BLOCK_MEASURE_INDICATOR_PREFIX}${range_id}`
+    const block_variables = blocks_in_range.map(
+        block => create_variable(block.get_id(), 1, VariableType.INTEGER)
+    )
+    block_variables.push(create_variable(indicator_name, -BIG_M, VariableType.INTEGER))
+    const name = `${UNIFORM_BLOCK_MEASURE_COUPLING_PREFIX}${range_id}`
+    return create_restriction(name, block_variables, { lower_limit: -BIG_M, upper_limit: 0 })
+}
+
+function build_cap_restriction(blocks_by_range)
+{
+    const variable_list = [...blocks_by_range.keys()].map(range_id =>
+        create_variable(`${UNIFORM_BLOCK_MEASURE_INDICATOR_PREFIX}${range_id}`, 1, VariableType.INTEGER)
+    )
+    return create_restriction(
+        UNIFORM_BLOCK_MEASURE_CAP_NAME,
+        variable_list,
+        { lower_limit: 0, upper_limit: 1 }
+    )
+}

package/src/Allocation_Optimization/next_group_id_after_preloaded.js

@@ -0,0 +1,30 @@
+function numeric_group_id(item)
+{
+    const item_group_id = item.get_group_id()
+    if (item_group_id === undefined || item_group_id === null)
+    {
+        return -1
+    }
+    const group_id = Number(item_group_id)
+    return Number.isFinite(group_id) ? group_id : -1
+}
+
+/**
+ * Keeps generated block group ids above preloaded numeric group ids.
+ * @param {object} container
+ * @param {number} current_next_group_id
+ * @returns {number}
+ */
+function resolve_next_group_id(container, current_next_group_id)
+{
+    if (typeof container.get_allocated_items !== 'function')
+    {
+        return current_next_group_id
+    }
+    const preloaded_group_ids = container.get_allocated_items()
+        .map(numeric_group_id)
+    const highest_group_id = Math.max(-1, ...preloaded_group_ids)
+    return Math.max(current_next_group_id, highest_group_id + 1)
+}
+
+module.exports = resolve_next_group_id

package/src/Allocation_Optimization/preferential_blocks/Preferential_Block_Identifier.js

@@ -0,0 +1,74 @@
+const Key_Item_Mapper = require('./key_item/Key_Item_Mapper')
+
+/**
+ * @class Preferential_Block_Identifier
+ * @description Identifies and marks blocks that are considered "preferential"
+ * based on a set of key items. A block is preferential if it can perfectly fit at least one key item.
+ */
+class Preferential_Block_Identifier
+{
+    #key_items
+
+    /**
+     * @constructor
+     * @description Initializes the Preferential_Block_Identifier by identifying key items.
+     * @param {object} transport - The transport object (container) against which key items are filtered.
+     * @param {Array<JSON>} items_to_allocate - The list of items that need to be allocated.
+     */
+    constructor( transport, items_to_allocate, key_item_mapper = new Key_Item_Mapper() )
+    {
+        this.#key_items = key_item_mapper.filter_key_items(transport, items_to_allocate)
+    }
+
+    /**
+     * Checks if a given block can perfectly fit any of the key items.
+     * @param {object} block - The block to check.
+     * @returns {boolean} - True if the block fits a key item, false otherwise.
+     */
+    #block_fits_key_item(block)
+    {
+        const slots = block.get_slot_list()
+        for (const key_item of this.#key_items)
+        {
+            for (const slot of slots)
+            {
+                if (slot.some_rotation_fits_perfectly(key_item))
+                {
+                    return true
+                }
+            }
+        }
+        return false
+    }
+
+    /**
+     * Iterates through a list of blocks and marks the ones that are preferential.
+     * @param {Array<object>} blocks - The list of blocks to evaluate.
+     */
+    mark_preferential_blocks(blocks)
+    {
+        let skip_all = true
+        for (const block of blocks)
+        {
+            if (block.get_slot_list().length > 1)
+            {
+                skip_all = false
+                break
+            }
+        }
+        if (skip_all)
+        {
+            return
+        }
+
+        for (const block of blocks)
+        {
+            if (block.get_slot_list().length > 1 && this.#block_fits_key_item(block))
+            {
+                block.set_preference()
+            }
+        }
+    }
+}
+
+module.exports = Preferential_Block_Identifier