API Reference

A predefined NetworkArc representing a zero-cost, zero-duration transition (e.g., waiting at a node).

abstract type AbstractArcCostFunction

Abstract base type for cost functions defined on network arcs. Concrete subtypes determine how load/size on an arc is translated into a financial or performance cost.

struct Arc{C<:AbstractArcCostFunction, K, T<:Dates.Period}

Representation of an arc in the network graph.

Fields

• origin_id::String: id of the origin node

• destination_id::String: id of the destination node

• travel_time::Dates.Period: travel time in number of discrete time steps (0 if less than the time discretization step)

• capacity::Int64: capacity of the arc (in size units)

• cost::AbstractArcCostFunction: cost function associated with the arc

• info::Any: additional information associated with the arc

struct Bin{C<:LightCommodity}

A representation of a bin/truck used in bin-packing cost functions.

Fields

• commodities::Vector{C} where C<:LightCommodity: List of commodities assigned to this bin

• total_size::Float64: Total size of all commodities in the bin

• max_capacity::Float64: Capacity of the bin

• remaining_capacity::Float64: Remaining capacity in the bin

struct BinPackingArcCost <: AbstractArcCostFunction

A bin-packing (or step) cost function. A fixed cost is incurred for each bin/truck needed.

Fields

• cost_per_bin::Float64: Fixed cost for each bin used (e.g., cost per truck)

• bin_capacity::Int64: Capacity of a single bin/truck

struct Bundle{O<:Order}

A collection of Orders that share the same origin and destination. While orders in a bundle can have different delivery dates, they should follow the same path (in the travel time graph).

Fields

• orders::Vector{O} where O<:Order

• origin_id::String

• destination_id::String

• forbidden_nodes::Set{String}: set of node IDs that are forbidden for this bundle (cannot be traversed)

• forbidden_arcs::Set{Tuple{String, String}}: set of arc (originid, destinationid) pairs that are forbidden for this bundle

struct Commodity{is_date_arrival, ID, I}

User-facing commodity data structure for parsing input data.

This structure is designed to be easy to instantiate from CSV, JSON, or other data sources. Once all commodities are loaded, they are consolidated into optimized internal structures (Commodity, Order, Bundle) based on problem-specific consolidation rules.

Type Parameters

• is_date_arrival::Bool:
  • true: date represents the arrival deadline at the destination.
  • false: date represents the earliest departure time (release) from the origin.
• ID: Type for node identifiers (e.g., String, Int).
• I: Type for additional problem-specific information.

Fields

• origin_id::Any: origin node identifier

• destination_id::Any: destination node identifier

• date::Dates.DateTime: date information associated with the commodity

• max_delivery_time::Dates.Period

• size::Float64: size of the commodity (we assume 1D approximation)

• quantity::Int64: quantity of the commodity

• forbidden_node_ids::Vector: list of forbidden node identifiers for this commodity

• forbidden_arcs::Array{Tuple{ID, ID}, 1} where ID: list of forbidden arcs for this commodity

• info::Any: additional problem-specific information

Examples

# Inbound logistics (arrival date)
Commodity(
    origin_id = "SUPPLIER_A",
    destination_id = "PLANT_PARIS",
    arrival_date = DateTime(2025, 11, 20),
    size = 150.0,
    info = (part_id = "ENGINE_V6", priority = :high)
)

# Outbound logistics (departure date)
Commodity(
    origin_id = "PLANT_PARIS",
    destination_id = "DEALER_LYON",
    departure_date = DateTime(2025, 11, 18),
    size = 1.0,
    info = (model = "Clio", color = "Blue")
)

Commodity(
;
    origin_id,
    destination_id,
    size,
    quantity,
    max_delivery_time,
    arrival_date,
    departure_date,
    forbidden_node_ids,
    forbidden_arcs,
    info
)

User-friendly constructor for Commodity.

struct Instance{B<:Bundle, G<:NetworkGraph, TSG<:TimeSpaceGraph, TTG<:TravelTimeGraph}

An Instance represents a transportation planning problem instance, containing bundles of orders, a network graph, and a time horizon.

Fields

• bundles::Vector{B} where B<:Bundle: list of bundles in the instance

• network_graph::NetworkGraph: underlying network graph

• time_horizon_length::Int64: length of the time horizon in discrete time steps

• time_step::Dates.Period: discretization time step for the instance

• time_step_to_date::Vector{Dates.Date}: mapping from time step index to date

• time_space_graph::TimeSpaceGraph: time expanded graph (for order paths)

• travel_time_graph::TravelTimeGraph: travel time graph (for bundle paths)

Instance(
    nodes::Vector{<:NetworkNode},
    arcs::Vector{<:Arc},
    commodities::Vector{Commodity{is_date_arrival,ID,I}},
    time_step::Period;
    group_by=_default_group_by,
    wrap_time=false,
) where {is_date_arrival,ID,I}

Construct an Instance from high-level Arc inputs by automatically inferring cost function types.

Arguments

• nodes::Vector{<:NetworkNode}: List of nodes in the spatial network.
• arcs::Vector{<:Tuple{String,String,<:NetworkArc}}: Arcs in the spatial network as (origin_id, destination_id, arc_data).
• commodities::Vector{Commodity}: User-facing commodity specifications.
• time_step::Period: The discrete time step size (e.g., Hour(1), Day(1)).

Keywords:

• group_by (default: _default_group_by): Optional function to group commodities into Orders (default: no additional grouping).
• wrap_time (default: false): whether the time horizon should wrap (cyclic)
• check_bundle_feasibility (default: true): whether to validate that bundles have feasible paths after applying forbidden constraints

Discretization and Normalization

1. Start Date: The time horizon starts at the earliest release date (for departure-based) or the earliest possible start (for arrival-based).
2. Time Steps: Dates and periods are converted to discrete steps using period_steps.
3. Consolidation: Commodities with the same origin, destination, and delivery step are grouped into Orders. Orders with the same origin and destination are grouped into Bundles for routing.
4. Graphs: Both TimeSpaceGraph (absolute time) and TravelTimeGraph (relative time) are constructed.

struct LinearArcCost <: AbstractArcCostFunction

A linear cost function where the cost is directly proportional to the total size/load on the arc.

Fields

• cost_per_unit_size::Float64: Unit cost per unit of size (e.g. m³, kg, etc.)

struct NetworkArc{C<:AbstractArcCostFunction, K}

Representation of an arc in the network graph.

Fields

• travel_time_steps::Int64: travel time in number of discrete time steps (0 if less than the time discretization step)

• capacity::Int64: capacity of the arc (in size units)

• cost::AbstractArcCostFunction: cost function associated with the arc

• info::Any: additional information associated with the arc

struct NetworkGraph{G<:MetaGraphsNext.MetaGraph}

A representation of the physical (spatial) network graph. Nodes are identified by String labels and store NetworkNode metadata. Edges store NetworkArc metadata.

Fields

• graph::MetaGraphsNext.MetaGraph: The underlying MetaGraph mapping node IDs (Strings) to metadata.

NetworkGraph(
    nodes::Vector{<:NetworkNode},
    arcs::Array{<:Tuple{String, String, NA<:NetworkArc}, 1}
) -> NetworkGraph{G} where G<:(MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, _A, _B, _C, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64} where {_A, _B, _C})

Constructor for NetworkGraph. Ensures node and arc IDs are unique during creation.

struct NetworkNode{J}

A node in the spatial network graph. Nodes represent physical locations and can serve as origins or destinations for commodities.

Fields

• id::String

• node_type::Symbol

• cost::Float64

• capacity::Int64

• info::Any

NetworkNode(; id, node_type, cost, capacity, info)

Constructor for NetworkNode.

Node Types (Symbol)

• :origin: A entry point for commodities.
• :destination: An exit point for commodities.
• :other: An intermediate or transhipment point.

struct Order{is_date_arrival, I}

An internal structure representing a group of commodities to be delivered together. Commodities in an Order share the same:

• Origin node
• Destination node
• Delivery date (interpreted as a deadline or release depending on is_date_arrival)

Type Parameters

• is_date_arrival::Bool: Inherited from the commodities. true for deadline-driven, false for release-driven.
• I: Additional problem-specific information.

Fields

• commodities::Array{LightCommodity{is_date_arrival, I}, 1} where {is_date_arrival, I}: list of commodities in the order

• time_step::Int64: time step corresponding to the delivery arrival/departure date

• max_transit_steps::Int64: maximum number of time steps for delivery among all commodities in the order

A small marker cost function used to represent shortcut / wait arcs. This makes dispatch and checks explicit instead of relying on numeric values.

struct Solution{C<:LightCommodity}

A solution to the network design optimization problem. It stores the chosen paths for each bundle in the TravelTimeGraph and precomputes key metrics such as commodity distributions on arcs and individual arc costs.

Fields

• bundle_paths::Vector{Vector{Int64}}: Paths for each bundle in the instance. bundle_paths[i] is a sequence of node codes in the TravelTimeGraph for the i-th bundle.

• commodities_on_arcs::Dict{Tuple{Int64, Int64}, Vector{C}} where C<:LightCommodity: Commodities on each arc of the TimeSpaceGraph. Maps (u, v) to a list of commodities.

• bin_assignments::Dict{Tuple{Int64, Int64}, Array{Bin{C}, 1}} where C<:LightCommodity: Bin assignments on each arc (for BinPackingArcCost arcs). Maps (u, v) to a list of bins.

• arc_costs::Dict{Tuple{Int64, Int64}, Float64}: Cost of each arc in the solution. Maps (u, v) to the arc's cost.

Solution(instance::Instance)

Initialize an empty solution for the given instance.

Solution(bundle_paths, instance)

Construct a Solution from bundle paths and an instance. This constructor precomputes commodity distributions on arcs, bin-packing results, and total cost.

struct TimeSpaceGraph{G}

A TimeSpaceGraph represents a time-expanded version of a network graph, where each node is replicated for each time step in the time horizon.

Fields

• graph::Any: underlying time-expanded graph

• time_horizon_length::Int64: length of the time horizon in discrete time steps

• wrap_time::Bool: whether time wrapping is enabled for arcs that exceed the time horizon

TimeSpaceGraph(
    network_graph::NetworkGraph,
    time_horizon_length::Int64;
    wrap_time
)

Constructor for TimeSpaceGraph. Creates timed copies of all nodes and arcs from the network_graph for each step in 1:time_horizon_length.

struct TravelTimeGraph{is_date_arrival, G<:MetaGraphsNext.MetaGraph}

A time-expanded graph where nodes represent (location, τ). The parameter is_date_arrival (boolean) defines the semantics of τ:

• is_date_arrival = true (Count Down / Remaining Time): τ represents the remaining time budget to meet a deadline.
  • Arcs move from τ to τ - travel_time.
  • Paths enter the graph at (origin, max_duration) and exit at (destination, 0).
• is_date_arrival = false (Count Up / Elapsed Time): τ represents the time elapsed since a release date.
  • Arcs move from τ to τ + travel_time.
  • Paths enter the graph at (origin, 0) and exit at (destination, max_duration).

Fields

• graph::MetaGraphsNext.MetaGraph: underlying time-expanded graph

• max_time_steps::Int64: Maximum duration allowed for a bundle in this graph

• cost_matrix::SparseArrays.SparseMatrixCSC{Float64, Int64}: Cost matrix between timed nodes (sparse)

• origin_codes::Vector{Int64}: Map from bundle index to unique origin node code entry point

• destination_codes::Vector{Int64}: Map from bundle index to unique destination node code exit point

• bundle_arcs::Vector{Vector{Tuple{Int64, Int64}}}: arcs usable for each bundle to ease looping through them

TravelTimeGraph(
    network_graph::NetworkGraph,
    bundles::Array{<:Bundle{<:Order{is_date_arrival, I}}, 1}
) -> TravelTimeGraph{_A, MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, Tuple{String, Int64}, NetworkNode, NetworkArc, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64}} where _A

Construct a TravelTimeGraph from a NetworkGraph and a set of Bundles.

getindex(
    travel_time_graph::TravelTimeGraph,
    label_1,
    label_2
) -> Any

Return edge metadata for the edge between label_1 and label_2.

getindex(travel_time_graph::TravelTimeGraph, label) -> Any

Return node metadata for label.

haskey(
    travel_time_graph::TravelTimeGraph,
    label_1,
    label_2
) -> Bool

Check if the travel-time graph has an edge between label_1 and label_2.

haskey(travel_time_graph::TravelTimeGraph, label) -> Bool

Check if the travel-time graph has a vertex with the given label.

show(io::IO, instance::Instance)

Return a summary of the instance.

add_edge!(
    travel_time_graph::TravelTimeGraph,
    u::Tuple{String, Int64},
    v::Tuple{String, Int64},
    arc::NetworkArc
) -> Bool

Add an arc between u and v with metadata arc to the travel-time graph.

add_vertex!(
    travel_time_graph::TravelTimeGraph,
    u::Tuple{String, Int64},
    node::NetworkNode
) -> Bool

Add a vertex with label u and metadata node to the travel-time graph.

has_edge(
    travel_time_graph::TravelTimeGraph,
    code_1::Integer,
    code_2::Integer
) -> Any

has_vertex(
    travel_time_graph::TravelTimeGraph,
    code::Integer
) -> Any

ne(travel_time_graph::TravelTimeGraph) -> Any

Get the number of edges in the travel-time graph.

nv(travel_time_graph::TravelTimeGraph) -> Any

Get the number of vertices in the travel-time graph.

weights(
    travel_time_graph::TravelTimeGraph
) -> SparseArrays.SparseMatrixCSC{Float64, Int64}

Get the weights (cost matrix) of the travel-time graph.

_add_network_arc!(
    time_space_graph::TimeSpaceGraph,
    origin::NetworkNode,
    destination::NetworkNode,
    arc::NetworkArc
)

_add_network_arc_to_travel_time_graph!(
    g::MetaGraphsNext.MetaGraph,
    origin::NetworkNode,
    destination::NetworkNode,
    arc::NetworkArc,
    max_time_steps::Int64,
    is_date_arrival::Bool
)

Add arcs corresponding to a network arc to the travel-time graph.

_add_network_node!(
    time_space_graph::TimeSpaceGraph,
    node::NetworkNode
)

Adds a timed copy of the given network node for each time step in the time horizon.

_add_network_node_to_travel_time_graph!(
    g::MetaGraphsNext.MetaGraph,
    node::NetworkNode,
    node_to_bundles_map::Dict{String, Array{B<:Bundle, 1}},
    max_time_steps::Int64,
    is_date_arrival::Bool
)

Add timed copies of a network node to the travel-time graph.

_compute_bundle_arcs(
    graph::MetaGraphsNext.MetaGraph,
    origin_codes::Vector{Int64},
    destination_codes::Vector{Int64}
) -> Vector{Vector{Tuple{Int64, Int64}}}

Compute usable arcs for each bundle by finding all arcs that lie on paths from the bundle's origin to its destination in the travel-time graph.

_is_shortcut_arc(arc::NetworkArc) -> Bool

Incrementally add a path (sequence of TTG node codes) for a bundle and update the solution. This updates bundle_paths, commodities_on_arcs, bin_assignments, and arc_costs.

build_instance(
    nodes::Vector{<:NetworkNode},
    raw_arcs::Vector{<:Arc},
    commodities::Array{Commodity{is_date_arrival, ID, I}, 1},
    time_step::Dates.Period,
    arc_cost_types::Tuple;
    group_by,
    wrap_time,
    check_bundle_feasibility
) -> Instance{B, G, TimeSpaceGraph{MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, Tuple{String, Int64}, NetworkNode, NetworkArc, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64}}, TTG} where {B<:(Bundle{Order{_A, _B}} where {_B, _A}), G<:(NetworkGraph{G} where G<:(MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, _A, _B, _C, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64} where {_A, _B, _C})), TTG<:(TravelTimeGraph{_A, MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, Tuple{String, Int64}, NetworkNode, NetworkArc, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64}} where _A)}

Build an Instance from raw_arcs::Vector{<:Arc} with explicit arc_cost_types for type stability.

This variant converts raw_arcs into NetworkArcs using collect_arcs(arc_cost_types, raw_arcs, time_step) and then delegates to build_instance(nodes, arcs, commodities, time_step; group_by, wrap_time).

build_instance(
    nodes::Vector{<:NetworkNode},
    arcs::Vector{<:Tuple{String, String, var"#s66"} where var"#s66"<:NetworkArc},
    commodities::Array{Commodity{is_date_arrival, ID, I}, 1},
    time_step::Dates.Period;
    group_by,
    wrap_time,
    check_bundle_feasibility
) -> Instance{B, G, TimeSpaceGraph{MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, Tuple{String, Int64}, NetworkNode, NetworkArc, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64}}, TTG} where {B<:(Bundle{Order{_A, _B}} where {_B, _A}), G<:(NetworkGraph{G} where G<:(MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, _A, _B, _C, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64} where {_A, _B, _C})), TTG<:(TravelTimeGraph{_A, MetaGraphsNext.MetaGraph{Int64, Graphs.SimpleGraphs.SimpleDiGraph{Int64}, Tuple{String, Int64}, NetworkNode, NetworkArc, Nothing, MetaGraphsNext.var"#MetaGraph##10#MetaGraph##11", Float64}} where _A)}

Build an Instance from normalized inputs.

This function expects nodes and arcs already in NetworkGraph form (i.e., arcs are tuples (origin_id, destination_id, NetworkArc)), and commodities are user-facing Commodity objects. In brief, it:

• Determines the instance start date (arrival- or departure-based) and converts dates into discrete time step indices using period_steps.
• Expands each Commodity into LightCommodity items and groups them into Orders (by time step, origin, destination and group_by) and Bundles (by origin, destination and group).
• Computes time_horizon_length (accounting for max_delivery_time unless wrap_time=true), constructs TimeSpaceGraph and TravelTimeGraph, and returns a populated Instance.

Arguments:

• nodes::Vector{<:NetworkNode}
• arcs::Vector{<:Tuple{String,String,<:NetworkArc}}
• commodities::Vector{Commodity}
• time_step::Period

Keywords:

• group_by (default: _default_group_by): function grouping commodities into orders
• wrap_time (default: false): whether the time horizon wraps (cyclic)
• check_bundle_feasibility (default: true): whether to validate that bundles have feasible paths after applying forbidden constraints

See also: the Instance constructor which accepts Arc inputs and performs automatic cost-type inference.

bundle_count(instance::Instance) -> Int64

Return the number of bundles in the instance.

collect_arcs(cost_types, arcs; validate=true)

Collect an iterable of NetworkArcs into a type-stable vector with the specified cost types. This is useful for creating heterogeneous arc collections with multiple cost function types while maintaining type stability.

Arguments

• cost_types: A tuple or Union of cost function types
  • Tuple syntax: (LinearArcCost, BinPackingArcCost)
  • Union syntax: Union{LinearArcCost, BinPackingArcCost}
• arcs: Iterable of NetworkArc objects with potentially different cost types
• validate: Whether to validate that all arc cost types are included (default: true)

Examples

# Using tuple (recommended)
arcs = [NetworkArc(cost=LinearArcCost(1.0), ...), NetworkArc(cost=BinPackingArcCost(2.0, 10), ...)]
typed_arcs = collect_arcs((LinearArcCost, BinPackingArcCost), arcs)

# Using Union (also works)
const MyCostTypes = Union{LinearArcCost, BinPackingArcCost}
typed_arcs = collect_arcs(MyCostTypes, arcs)

commodity_count(instance::Instance) -> Any

Return the number of commodities in the instance.

compute_bin_assignments(
    arc_f::BinPackingArcCost,
    commodities::Array{C<:LightCommodity, 1}
) -> Vector

Compute the bin assignments for a list of commodities using the First-Fit Decreasing (FFD) heuristic. Returns a vector of Bin objects.

compute_node_to_bundles_map(
    bundles::Array{B<:Bundle, 1}
) -> Dict{String, Vector{B}} where B<:Bundle

Compute a mapping from node IDs to the list of bundles that originate from that node.

compute_ttg_edge_incremental_cost(sol, instance, bundle, u_ttg_label, v_ttg_label)

Compute the incremental cost of a TravelTimeGraph edge for a specific bundle, considering all its orders and their projections to the TimeSpaceGraph.

cost(sol::Solution, instance::Instance) -> Float64

Compute the cost of the solution (legacy signature for compatibility).

cost(sol)

Compute the cost of the solution by summing individual arc costs.

evaluate(
    arc_f::AbstractArcCostFunction,
    commodities::Vector{<:LightCommodity}
) -> Float64

Fallback evaluate for unknown cost function types.

evaluate(
    arc_f::BinPackingArcCost,
    commodities::Vector{<:LightCommodity}
) -> Float64

Evaluate the cost of transporting a list of commodities on an arc with a bin-packing cost function. The cost is based on the number of bins (trucks) needed to transport all commodities. Uses the First-Fit Decreasing (FFD) heuristic to determine bin assignments and count.

evaluate(
    arc_f::LinearArcCost,
    commodities::Vector{<:LightCommodity}
) -> Float64

Evaluate the cost of transporting a list of commodities on an arc with a linear cost function. The cost is proportional to the total size of all commodities.

greedy_heuristic(
    instance::Instance
) -> Solution{LightCommodity{_A, _B}} where {_A, _B}

Construct a solution by inserting bundles one by one into an initially empty solution. Bundles are processed in the order they appear in the instance.

incremental_cost(arc_f::AbstractArcCostFunction, existing_commodities, new_commodities)

Compute the additional cost of adding new_commodities to an arc that already contains existing_commodities.

infer_cost_types(arcs::Vector{<:Arc}) -> Tuple

Infer the cost types present in a vector of arcs by scanning their actual cost function types. Returns a tuple of unique cost types found in the arcs.

This is a runtime operation that enables automatic cost type detection, but the result can be passed to type-stable inner functions via function barriers.

insert_bundle!(sol, instance, bundle_idx)

Find the cheapest path for a bundle in the TravelTimeGraph (considering incremental costs) and add it to the solution.

is_feasible(
    sol::Solution,
    instance::Instance;
    verbose
) -> Bool

Check if a solution is feasible for a given instance. Feasibility requires:

1. Every bundle in the instance must have a corresponding path in the solution.
2. Every path must exist (each arc exists in the graph).
3. Every path must start at the bundle's designated entry node (origin_codes).
4. Every path must end at the bundle's designated exit node (destination_codes).

order_count(instance::Instance) -> Int64

Return the number of orders in the instance.

period_steps(p::Period, step::Period; roundup=floor)::Int

Compute how many complete step units fit into period p.

Arguments

• p::Period: the period to measure
• step::Period: the step size
• roundup::Function: ceil (default) or floor

Returns

An integer representing the number of steps.

Examples

period_steps(Day(10), Week(1))                    # => 2 (default ceil)
period_steps(Day(10), Week(1); roundup=floor)     # => 1
period_steps(Hour(25), Week(1))                   # => 1
period_steps(Day(1), Hour(12); roundup=floor)     # => 2

project_bundle_path_to_order_paths(
    sol::Solution,
    instance::Instance
) -> Dict{Order, Vector{Int64}}

Project bundle paths to order paths on the Time Space Graph. Returns a Dict mapping Order to a Vector of TSG node codes (Int).

project_to_time_space_graph(
    ttg_node_code::Int64,
    order::Order{is_date_arrival},
    instance::Instance
) -> Integer

Project a node code from the TravelTimeGraph to a node code in the TimeSpaceGraph for a specific order. The projection converts the graph-specific time τ (budget or elapsed) into absolute time t in the TimeSpaceGraph.

Time Projection Formulas

• If is_date_arrival = true: t = deadline - τ
• If is_date_arrival = false: t = release + τ

Throws a DomainError if the resulting t is outside the instance time horizon [1, time_horizon_length].

read_solution_csv(filename::String, instance::Instance)

Read a solution from a CSV file and reconstruct the Solution object. Assumes the CSV follows the format: route_id,origin_id,destination_id,node_id,point_number,point_type.

time_horizon(instance::Instance) -> UnitRange{Int64}

Return the time horizon of the instance as a range of discrete time steps.

time_horizon(g::TimeSpaceGraph) -> UnitRange{Int64}

Returns the range of time steps in the time space graph.

time_horizon(
    travel_time_graph::TravelTimeGraph
) -> UnitRange{Int64}

Get the time horizon of the travel-time graph.

total_size(bundle::Bundle) -> Float64

Compute the total size of all commodities in the bundle.

total_size(order::Order) -> Float64

Compute the total size of all commodities in the order.

travel_time_steps(arc::NetworkArc) -> Int64

Return the travel duration (in discrete steps) associated with the arc.

validate_bundle_feasibility(
    ttg::TravelTimeGraph,
    bundle_idx::Int64,
    bundle::Bundle
) -> Bool

Validate that a bundle can reach its destination from its origin while respecting forbidden constraints.

Uses BFS to check reachability in the TravelTimeGraph, avoiding forbidden nodes and arcs. Explores all edges in the time-expanded graph to check if ANY feasible path exists. Returns true if the bundle is feasible, false otherwise.

write_solution_csv(filename::String, sol::Solution, instance::Instance)

Write the solution to a CSV file in the following format: route_id,origin_id,destination_id,node_id,point_number,point_type

The paths are written in reverse order (from destination to origin) to match the user's requested format.