NS3 Solution ResponseSolution Response
Overview
The solution response contains the details of the optimal solution found by the solver corresponding to a valid solve request. The important features of the solution, such as which lane rates and cost models were used by the solver in the final solution, the product-level flow per node, and the aggregate flow over a node, are returned in this payload.
This allows the user to interrogate the costs associated with different actions performed by the solver as well as any constraints which could not be met (through incurred penalty costs).
Applicable models
- NS3
ns3-tbfvuwtge2iq
Endpoint
Assignment
The assignment portion of the solution response contains the information regarding product movements between locations. The data are returned at a source-destination, lane rate / cost model level per product.
Schema definition
message Assignment {
required string source = 1;
required string destination = 2;
required string productId = 3;
required float amount = 4;
required float cost = 5;
optional string laneRateId = 6;
optional string costModelId = 7;
required float distance = 8;
required float duration = 9;
}
Fields
- source
- The source node of the assignment used by the solver.
- destination
- The destination node of the assignment used by the solver.
- productId
- The product ID applicable to this assignment item.
- amount
- The quantity applied to this assignment.
- cost
- The cost of this product-assignment.
- laneRateId
- If applicable, the lane rate identifier from the input model.
- costModelId
- If applicable, the cost model identifier from the input model.
- distance
- If distance is a defined internal dimension for the model, the distance between the source and destination is returned, otherwise a zero is returned.
- duration
- If time is a defined internal dimension for the model, the duration between the source and destination is returned, otherwise a zero is returned.
Examples
This example shows an assignment returned by the solver which uses a cost per unit weight for the product Beer
between the Guiness Storehouse and the Galway Warehouse. Distance and duration are set to zero in this context because the costing did not use distance or duration in the calculation. The assignment item also shows the lane rate selected and the amount which was moved between the source and destination.
source: "Guiness Storehouse"
destination: "Galway Warehouse"
productId: "Beer"
amount: 116
cost: 2397.8186
laneRateId: "lr:Guiness Storehouse->Galway Warehouse"
distance: 206.708496
duration: 2.38080549
This next example illustrates the use of a cost model for the product Beer
between the Guiness Storehouse and the node 3
. Note that either the costModelId
or the laneRateId
will be populated, never both.
source: "Guiness Storehouse"
destination: "3"
productId: "Beer"
amount: 42
cost: 84.2864761
costModelId: "costmodel: Guiness Storehouse:Beer"
distance: 10.0341043
duration: 0.290583342
Node Product Flow
The node product flow response provides a summary of the product quantities which flow over a specified node. For production and consumption nodes, the penalty amounts (if applicable) and production or consumption amounts are specifically provided. This indicates when product is created (produced) or destroyed (consumed) in the network. The cost of manufacturing is reflected in the productionCost
field and, similarly, the cost of not supplying a target demand amount is reflected in the consumptionPenalty
field.
Schema definition
message NodeProductFlow {
required string nodeId = 1;
required string productId = 2;
required float inFlow = 3;
required float outFlow = 4;
required float flowCost = 5;
required float fixedCost = 6;
required float productionAmount = 7;
required float productionPenalty = 8;
required float productionCost = 9;
required float consumptionAmount = 10;
required float consumptionPenalty = 11;
required float consumptionCost = 12;
}
Fields
- nodeId
- The unique node identifier, corresponding to the identifiers provided per node in the model.
- productId
- The product identifier which this particular entity refers to.
- inFlow
- The total quantity for the specified product that flows into this node.
- outFlow
- The total quantity for the specified product that flows out of this node.
- flowCost
- The cost associated with the product quantity that flows over this node.
- fixedCost
- Any fixed costs incurred by this node.
- productionAmount
- If a production node, the total product quantity added to the network, zero otherwise.
- productionPenalty
- If a production node, the total penalty incurred by the node if the
productionAmount
is not within the specified dimension range, and zero otherwise. - productionCost
- If a production node, the total cost associated with the product created at this node as a result of specified unit dimensional costs.
- consumptionAmount
- If a consumption node, the total production quantity removed from the network at this node, zero otherwise.
- consumptionPenalty
- If a consumption node, the total penalty incurred by the node if the
consumptionAmount
is not within the specified dimension range, and zero otherwise. - consumptionCost
- If a consumption node, the total cost associated with the product consumed at this node, zero otherwise.
Examples
In this example, the Guiness Storehouse produces 5119 units of Beer
which is then sent out of the node (through the lane rates / cost models) to other nodes. One might note that there are no penalties associated with the production amount, as it was unbounded in the particular input model. The sum of the inflow and production amount equals the sum of the outflow and consumption amount.
nodeId: "Guiness Storehouse"
productId: "Beer"
inFlow: 0
outFlow: 5119
flowCost: 0
fixedCost: 0
productionAmount: 5119
productionPenalty: 0
productionCost: 0
consumptionAmount: 0
consumptionPenalty: 0
consumptionCost: 0
In this next example, we show the product node flow for a consumption node. The consumption amount is equal to the inflow (76) and no further product flows onwards from this node (the outFlow is zero).
nodeId: "4"
productId: "Beer"
inFlow: 76
outFlow: 0
flowCost: 0
fixedCost: 0
productionAmount: 0
productionPenalty: 0
productionCost: 0
consumptionAmount: 76
consumptionPenalty: 0
consumptionCost: 0
This last snippet illustrates a warehouse node. There is no production or consumption on this node, and the inflow equals the outfow. There is a small flow cost proportional to the units moved through the warehouse (1.5 monetary units per unit flow).
nodeId: "Galway Warehouse"
productId: "Beer"
inFlow: 116
outFlow: 116
flowCost: 174
fixedCost: 0
productionAmount: 0
productionPenalty: 0
productionCost: 0
consumptionAmount: 0
consumptionPenalty: 0
consumptionCost: 0
NodeFlow
The node flow definition is very similar to the node product flow, except that it aggregates the quantities, costs and penalties across all products. This is used when one is attempting to look at the total flow movements through warehouses or manufacturing nodes.
Schema definition
message NodeFlow {
required string nodeId = 1;
required float inFlow = 2;
required float outFlow = 3;
required float flowCost = 4;
required float fixedCost = 5;
required float productFlowCost = 6;
required float productFixedCost = 7;
required float productionAmount = 8;
required float productionPenalty = 9;
required float productionCost = 10;
required float consumptionAmount = 11;
required float consumptionPenalty = 12;
required float consumptionCost = 13;
}
Fields
- nodeId
- This node identifier pertaining to this item.
- inFlow
- The total inflow across all products for this node.
- outFlow
- The total outflow across all products for this node.
- flowCost
- The total cost across all flow-level unit dimensional costs defined on a node. This excludes product flow costs which are reported separately, allowing the user to aggregate these quantities if required.
- fixedCost
- The total fixed cost incurred for all flow-level fixed cost attributes. This is reported separately from the aggregate product flow fixed costs so that the user can easily decompose the origin of fixed costs.
- productFlowCost
- The total cost across all products for this node.
- productFixedCost
- The total fixed cost incurred across all products for this node.
- productionAmount
- The total quantity added to the network at this node across all products.
- productionPenalty
- The total production penalty across all products at this node.
- productionCost
- The total production cost across all products at this node.
- consumptionAmount
- The total consumption quantity across all products at this node.
- consumptionPenalty
- The total consumption penalty cost across all products at this node.
- consumptionCost
- The total consumption cost across all products at this node.
GeometrySequence
Network sourcing models which are submitted to the solver with the geometryOutput
field set to Aggregate
will have a list of geometry sequences populated in the solution output. Each geometry sequence represents a common linestring which is used by an origin-destination pair (see Route
below). The order of the data in both the GeometrySequence and the Route is important for the correct interpretation of the data. The geometry sequence is ordered such that each point forms the next location in a linestring.
Schema definition
message GeometrySequence {
repeated float x = 1;
repeated float y = 2;
}
Fields
- x
- A list of longitude values corresponding to a valid linestring
- y
- A list of latitude values (the lane number as field
x
above) corresponding to a valid linestring.
Examples
This example illustrates a simple linestring with two points.
x: -6.39891577
x: -6.39914
y: 53.5125122
y: 53.5126457
Route
A route definition in the context of the sourcing-model corresponds to an origin-destination pair for either a cost model or lane rate. A list of integers (geometrySequence
) is provided by the route object which corresponds to the zero-based indexes of each portion of the linestring that contributes to this origin-destination pair. The master list of geometry sequences is provided on the SolutionResponse
.
Schema definition
message Route {
required string fromId = 1;
required string toId = 2;
repeated int32 geometrySequence = 3;
}
Fields
- fromId
- The origin node for this particular route, corresponding to the node identifiers passed in the input model.
- toId
- The destination node for this particular route, corresponding to the node identifiers passed in the input model.
- geometrySequence
- An ordered list of zero-based indexes corresponding to the next valid linestring from the
SolutionResponse.geometrySequence
object required to complete the route. One can consider this as a list of partial routes which can be concatenated together in the order presented here to form one larger linestring. See the R, Python, C# and Java coding examples for an example algorithm to extract the complete geometry.
Examples
This example illustrates a simple geometry Route object which defines a path from Limerick Warehouse
to node 19
. There are 8 common path-sequences which can be concatenated in the order 0, 1, …, 7 from the SolutionResponse.geometrySequence
to form the complete path for visualisations.
fromId: "Limerick Warehouse"
toId: "19"
geometrySequence: 0
geometrySequence: 1
geometrySequence: 2
geometrySequence: 3
geometrySequence: 4
geometrySequence: 5
geometrySequence: 6
geometrySequence: 7
Solution Response
The solution response is the parent container for assignment, node flow and geometry information returned by the solver.
Schema definition
message SolutionResponse {
required float objective = 1;
optional float lowerBound = 2;
optional float optimalityGap = 3;
repeated Assignment assignments = 4;
repeated NodeFlow nodeFlows = 5;
repeated NodeProductFlow nodeProductFlows = 6;
repeated GeometrySequence geometrySequence = 7;
repeated Route routes = 8;
}
Fields
- objective
- The total cost of the solution found by the solver.
- lowerBound
- The lower bound of the solution cost. This is a theoretical absolute minimum cost a solution may take on. The solver can prove (mathematically) that no feasible solution exists below this value and is thus a lower-bound.
- optimalityGap
- The optimality gap is the remaining search space between the current solution found by the solver and the lower bound. In instances where an optimality proof is provided, the optimality gap will be zero.
- assignments
- A list of assignments used by the solver in the solution.
- nodeFlows
- A list of node flows used by the solver in the solution.
- nodeProductFlows
- A list of product node flows used by the solver in the solution.
- geometrySequence
- A master list of common geometry sequences used by the
routes
. Each item forms a partial linestring used by some subset of routes in the solution. - routes
- A list of origin destination pairs and their geometrySequence indexes (zero-based) required to construct a full path from the origin to the destination.
For examples of solution responses we recommend exploring the examples repo which has coding examples in R, Python, C# and Java.