NS3 NodeNode

Overview

The node forms a core component in the sourcing model, describing a location in the network through which commodities may flow. Nodes are loosely grouped into one of three categories: production, consumption and intermediate nodes. Production nodes specify the production field which indicates that products are produced at these locations. Consumption nodes populate the consumption field indicating that products are consumed at these locations. When neither a production nor consumption is provided, the node is assumed to be an intermediate node (through which products can potentially flow without creating or depleting the product). Flow constraints can still be placed on a node by using the productFlows field (to model warehouse maximum flows or product constraints on an intermediate node).

Dimensional ranges are typically specified for production and consumption to indicate where product is created and where it is required to be delivered.

Applicable models

• NS3 ns3-tbfvuwtge2iq

Node Product Flow

A node product flow is used to describe constraints, fixed costs (for any non-zero flow amount) and costs associated with a product at a particular node. In the context of production nodes, this is used to describe production costs and capabilities. In the context of consumption nodes, this is used to describe the target amount that should be sent to a particular consumption node in the network. In the context of intermediate nodes, this is used to limit the maximum amount of product which can flow through a particular warehouse, or the cost of moving a product through a warehouse.

Schema definition

message ProductFlow {
  required string productId = 1;
  repeated DimensionRange dimensionRanges = 2;
  repeated FixedDimensionCost FixedDimensionCosts = 3;
  repeated UnitDimensionCost unitDimensionCosts = 4;
}

Fields

productId

The unique identifier of the product to which the costing, dimension range or fixed costs apply.

dimensionRanges

A list of dimension ranges which are applicable to the product. Dimension ranges provide a soft-constraint interface on the minimum and maximum which should flow from/to the node associated with this product flow.

FixedDimensionCosts

A list of fixed dimension costs associated with the product flow. This is useful to trigger fixed costs which are applicable should any non-zero dimensional quantity associated with this product be used.

unitDimensionCosts

A list of unit dimension costs associated with the product flow. This is used to model cost per unit dimension applied at this node, such as manufacturing costs or warehouse storage costs.

Examples

This example illustrates a typical production node product flow configuration. The production plant can product a maximum of 10,000 kilograms and if more is produced a large penalty is incurred. In a situation where multiple production facilities are being investigated, it is typical to add a fixed dimension cost, which helps choose between facilities (i.e. if a facility is used to produce any amount of Beer, a fixed cost of 1000 monetary units is applied to the cost equation).

productId: "Beer"
dimensionRanges {
  dimensionId: "weight"
  minRange: 0
  maxRange: 10000
  flowPenalty: 1e+06
}
FixedDimensionCosts {
  dimensionIds: "weight"
  fixedCost: 1000
}

This next example illustrates a simple product flow configuration for a consumption node. The dimension ranges require that 20 units are provided to this particular node, otherwise a large flow penalty is incurred. This ensures that if a node can be serviced feasibly, it will be, otherwise it will allow the user to identify where the primary capacity constraints are that prohibit the node from being serviced.

id: "Beer"
dimensionRanges {
  dimensionId: "weight"
  minRange: 20
  maxRange: 20
  flowPenalty: 1e+06
}

As a last example, we provide a typical configuration of an intermediate node’s product flow configuration. In this example, the maximum weight that can flow through this node configuration is 5000 units. There is a 100 monetary unit cost if the warehouse is used and for each unit of product volume that flows through the warehouse (to satisfy consumption nodes) a cost of 0.5 monetary units per quantity is added to the cost equation. This allows a user to model the handling cost through a warehouse, as well as the annualised fixed cost of opening the warehouse.

id: "Beer"
dimensionRanges {
  dimensionId: "weight"
  minRange: 0
  maxRange: 5000
  flowPenalty: 1e+06
}
FixedDimensionCosts {
  dimensionIds: "weight"
  fixedCost: 100
}
unitDimensionCosts {
  dimensionIds: "weight"
  dimensionCoefficients: 1
  costPerUnit: 0.5
}

Node Flow

The flow definition provides the same functionality as the product flow except that it aggregates all dimensional quantities across all products. This means that constraints can be applied across multiple products which have dimensional contributions to a particular node. In real world examples, this is used to model constraints at locations across resources which share certain product dimensions. As an example, there may be equipment which is required to manufacture products A and B, the individual manufacturing capacity of products A and B may already be constrained through a ProductFlow definition, however, they share floor space in the plant and the total production of A and B should be less than a given amount. The same logic is applied to the fixed dimensional costs and the unit dimensional costs which allow the triggering of fixed costs across products or the costing across multiple products which share common dimensions.

Schema definition

message Flow {
  repeated DimensionRange dimensionRanges = 1;
  repeated FixedDimensionCost FixedDimensionCosts = 2;
  repeated UnitDimensionCost unitDimensionCosts = 3;
}

Fields

dimensionRanges

A list of dimension ranges which are applicable across all products at this node. Dimension ranges provide a soft-constraint interface on the minimum and maximum which should flow from/to the node associated with this flow.

FixedDimensionCosts

A list of fixed dimension costs associated with the flow. This is useful to trigger fixed costs which are applicable should any non-zero dimensional quantity associated with all product dimensions be used.

unitDimensionCosts

A list of unit dimension costs associated with the flow. This is used to model cost per unit dimensions applied at this node, such as manufacturing costs or warehouse storage costs across all products.

Node Product Transform

The node product transform definition provides the target node with the ability to transform a specified amount of one product into another. This relationship need not be a 1:1 relationship (one product in, one product out) and supports 1:many, many:1 and many:many. This top level interface allows one to specify the input and output product transform items which should be applied at the node.

Schema definition

message ProductTransform { 
  required string productTransformId = 1;
  repeated Item inputItems = 2;
  repeated Item outputItems = 3;
}

Fields

productTransformId

A unique identifier for this product transform. The identifier provided is used in the solution response payload.

inputItems

A list of input product definitions used by the product transformer. The list should consist of at least one item.

outputItems

A list of output product definitions used by the product transformer. The list should consist of at least one item.

Notes

• It’s important to remember that the NS3 model will preserve the flow of quantities in the network. This means that, if you have product transforms that produce multiple output quantities, the quantities need to go somewhere or the solver won’t be able to use them.
• A normal modelling trick is to add an extra lane to a dummy node which can then consume the “excess” produced at a slightly higher rate than the normal cost. This allows the solver to produce excess waste in the transformation of a product if needed.

Node Product Transform Item

A Node Product Transform Item defines a single term used in either the input or output of a Product Transform. The definition allows a user to define a cost per unit transformed, fixed cost triggers or dimensional constraints which can be applied at a term level.

Schema definition

message Item {
  required string productId = 1;
  required int32 productRatio = 2;
  repeated DimensionRange dimensionRanges = 3;
  repeated FixedDimensionCost fixedDimensionCosts = 4;
  repeated UnitDimensionCost unitDimensionCosts = 5;
}

Fields

productId

The product identifier for this Product Transform Item.

productRatio

The integer ratio amount which should be applied to this particular Product Transform Item. Integer values are required here as most fractional ratios can be reasonably approximated by an integer ratio. I.e the ratio 1:0.333… should rather be written as 3:1.

dimensionRanges

A list of dimension range constraints which may apply to this particular product. It is possible to restrict the maximum amount of a particular product that may be used by this particular transform item.

fixedDimensionCosts

A list of fixed dimension costs associated with using this particular product transform item. This is often use to trigger a fixed cost (often representing some capital expenditure) in the model if any non-zero quantity is used in this transform item.

unitDimensionCosts

A list of unit dimension costs associated with this particular product transform item. This is useful for modelling the cost of the transform per unit product employed in the transformation.

Node

The node describes a particular location in the network, along with its constraints and costs. The costs in this context are internal to the node (i.e. manufacturing, consumption or warehousing). Costs or constraints associated with moving product between nodes can be modelled using either lane rates or cost models.

Schema definition

message Node {
  required string id = 1;
  required Geocode geocode = 2;
  repeated ProductFlow production = 3;
  repeated ProductFlow consumption = 4;
  optional Flow flow = 5;
  repeated ProductFlow productFlows = 6;
  repeated string allowableSources = 7;
  optional int32 maximumSources = 8 [default = -1];
  repeated FlowDimensionalConstraint flowConstraints = 9;
  repeated ProductTransform productTransforms = 10; 
}

Fields

id

A unique identifier for this node. Duplicate nodes are not permitted in a model.

geocode

The geographic location of this node. This interface to the solver requires that geocodes are positioned on the face of planet earth in decimal degrees.

production

ProductFlow constraints and costs associated with this node. The context of this field allows the creation of products in the network which can then be sent to consumption nodes.

consumption

ProductFlow constraints and costs associated with this node. The context of this field allows the consumption of products in the network which is typically associated with demand nodes which require the delivery of products.

flow

The flow associated with this node which allows for the costing or dimensional constraints which are applied across all products.

productFlows

ProductFlow constraints and costs associated with the node. The context of this field allows the constraining or costing of products through the node, which is typically associated with intermediate nodes (or warehouses) in the network.

allowableSources

A list of allowable sources for this particular node. In networks where cost models are used, this allows a simple interface to specify which nodes may provide products to the node in question. This is often useful to encapsulate real-world constraints where certain locations may not supply the target node (due to logistic, geographic or other constraints). Allowable sources should contain nodes which are defined in the current model. If a node id is provided which is not defined in the current model, the solver will report an error.

maximumSources

The maximum number of nodes which may supply the node being defined. This is useful in situations where a node is positioned in a somewhat indifferent position geographically which may easily be serviced by multiple nodes. It is also typical to apply a constraint of 1 to consumption (or demand) nodes in order to break ties where a node may be serviced by multiple nodes as it may not be a practical policy to service a customer from multiple facilities.

flowConstraints

A list of flow dimensional constraints which should be applied to this node. This is useful to model warehouse capacities.

productTransforms

A list of product transforms which should be applied at this node. This is useful when modelling the production of certain products which require other product types in their manufacturing.

Examples

This example defines a simple node where an unbounded amount of Beer can be manufactured at the location. The dimension range in this example is defined with no flow penalty which tells the solver that the node can produce beer (as it is defined on the production attribute) but there is no penalty for exceeding the limit.

id: "Guiness Storehouse"
geocode {
  longitude: -6.28655
  latitude: 53.34161
}
production {
  id: "Beer"
  dimensionRanges {
    dimensionId: "weight"
    minRange: 0
    maxRange: 10000
    flowPenalty: 0
  }
}

This next snippet defines a warehouse in Galway which may only be supplied from the Guiness Storehouse. It would not be necessary to set the maximum allowable sources in this example as there is only one permissible source in the allowableSources field. The warehouse uses the node flow property to cost each unit of weight moved through the warehouse at 0.5 monetary units per unit weight (the dimension)

id: "Galway Warehouse"
geocode {
  longitude: -9.03500748
  latitude: 53.3023
}
flow {
  unitDimensionCosts {
    dimensionIds: "weight"
    dimensionCoefficients: 1
    costPerUnit: 0.5
  }
}
allowableSources: "Guiness Storehouse"

This last example illustrates a demand node definition which has populated the consumption field with a product flow requirement of 20 units which, if not satisfied by the solution to the network, will incur a large flow penalty. Only two allowable sources are permitted for this node which exclude the “Guiness Storehouse” from a feasible solution.

id: "1"
geocode {
  longitude: -6.26393
  latitude: 53.4318504
}
consumption {
  id: "Beer"
  dimensionRanges {
    dimensionId: "weight"
    minRange: 20
    maxRange: 20
    flowPenalty: 1e+06
  }
}
allowableSources: "Galway Warehouse"
allowableSources: "Limerick Warehouse"